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Chapter 1 Introduction to JasperReports Server 


TIBCO JasperReports® Server builds on TIBCO JasperReports® Library as a comprehensive family of Business 
Intelligence (BI) products, providing robust static and interactive reporting, report server, and data analysis 
capabilities. These capabilities are available as either stand-alone products, or as part of an integrated end-to-end 
BI suite utilizing common metadata and provide shared services, such as security, a repository, and scheduling. 
The server exposes comprehensive public interfaces enabling seamless integration with other applications and 
the capability to easily add custom hmctionality. 


This section describes functionality that can be restricted by the software license for JasperReports 
Server. If you don’t see some of the options described in this section, your license may prohibit you from 
using them. To find out what you're licensed to use, or to upgrade your license, contact Jaspersoft. 


The heart of the TIBCO Jaspersoft® BI Suite is the server, which provides the ability to: 

• Easily create new reports based on views designed in an intuitive, web-based, drag and drop Ad Hoc 
Editor. 

• Efficiently and securely manage many reports. 

• Interact with reports, including sorting, changing formatting, entering parameters, and drilling on data. 

• Schedule reports for distribution through email and storage in the repository. 

• Arrange reports and web content to create appealing, data-rich Jaspersoft Dashboards that quickly convey 
business trends. 

For users interested in multi-dimensional modeling, we offer Jaspersoft® OLAP, which mns as part of the server. 

While the Ad Hoc Editor lets users create simple reports, more complex reports can be created outside of the 

server. You can either use Jaspersoft® Studio or manually write JRXML code to create a report that can be mn 

in the server. We recommend that you use Jaspersoft Studio unless you have a thorough understanding of the 

JasperReports file stmcture. See “Adding Reports Directly to the Repository” on page 175 and the TIBCO 

Jaspersoft Studio User Guide for more information. 

You can use the following sources of information to learn about JasperReports Server: 

• Our core documentation describes how to install, administer, and use JasperReports Server and Jaspersoft 
Studio. Core documentation is available as PDFs in the doc subdirectoiy of your JasperReports Server 
installation. You can also access PDF and HTML versions of these guides online from the Documentation 
section of the Jaspersoft Community website. 

• Our Ultimate Guides document advanced features and configuration. They also include best practice 
recommendations and numerous examples. You can access PDF and HTML versions of these guides online 
from the Documentation section of the Jaspersoft Community website. 
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• Our Online Learning Portal lets you learn at your own pace, and covers topics for developers, system 
administrators, business users, and data integration users. The Portal is available online from the Professional 
Services section of our website . 

• Our free samples, which are installed with JasperReports Library, Jaspersoft Studio, and JasperReports 
Server, are available and documented online. Please visit our GitHub repository . See ^‘Adding Reports 
Directly to the Repository” on page 175 and TIBCO Jaspersoft Studio User Guide for more information. 

• If you have a subscription to our professional support offerings, please contact our Technical Support team 
when you have questions or mn into difficulties. They're available on the web at and through email at 
http://support.tibco.com and js-support@tibco.com . 

JasperReports Server is a component of both a community project and commercial offerings. Each integrates the 

standard features such as security, scheduling, a web services interface, and much more for mnning and sharing 

reports. Commercial editions provide additional features, including Ad Hoc views and reports, advanced charts, 

dashboards. Domains, auditing, and a multi-organization architecture for hosting large BI deployments. 

This chapter contains the following sections: 

• Logging In 

• The Getting Started Page 

• The Library Page 

• Browsing the Repository 

• Searching the Repository 

• Using Repository Resources 

• Sorting the Repository List 


.1 Logging In 

Launch JasperReports Server by entering http: //<hostname>: 8080 /jasperserver-pro in a web browser, 
where <hostname> is the name of the computer that hosts JasperReports Server. The Login page appears. 
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Welcome to Jaspersoft 


Help 

Getting Started 



[5 How-to videos 

TIBC® Jaspersoft 


[5 How-to articles 

(Z Product documentation 

User ID: 


[5 Find the right edition for you 



(Z Jaspersoft Quick Start Guide 

Password: 


What's new in Jaspersoft Version 7? 

Show locale & time zone 


Visualize.js: 

H Login H 


Support for embedding Ad Hoc Views with hyperlink 
support and CSS Inheritance 

Need help logging in? 


Flesh New Uls: 

New Home Page, Designer and Viewer Uls, and Gauge 

Visualizations 

Domains: 

All-new user experience and more advanced features for 
joining data 

Jaspersoft Studkx 

Support for TIBCO JasperReports* lO and TIBCO Spotfire* 

Information Links 




Figure 1-1 Jaspersoft Login Page 



To log in to the server, JavaScript and cookies must be enabled in your browser. 


Before logging in, review the information on the login page. There are links to the online help and additional 
resources. 

You can log in as the following users: 

• superuser/superuser to manage configuration and organizations 

• jasperadmin/jasperadmin to manage a single organization 

• joeuser/joeuser to see an end user's view 

• demo/demo to view the demo dashboard, if samples were installed 



For security reasons, administrators should always change the default passwords immediately after installing 
JasperReports Server, as described in the TIBCO JasperReports Server Administrator Guide. 


To log in to the server: 

1. Enter your user ID and password. 



If you installed an evaluation server with the sample data, you can log in with the sample user IDs and 
passwords. For more information, click Need help logging in? 

If the Organization field appears in the Login panel, enter the ID or alias of your organization. If you don’t know 
it, contact your administrator. For more information, see “Logging into a Server with Muitipie Organizations” 
on page 10. 

The default administrator login credentials are superuser/superuser and jasperadmin/jasperadmin. 


TIBCO Software Inc. 


9 






TIBCO JasperReports Server User Guide 


2. If you want to use a different locale and time zone than the server uses, click Show locale & time zone. 
The Locale and Time Zone fields appear in the Login panel. Select your locale and time zone from the 
drop-down menus. 

3. Click Login. 

If you entered a valid user ID and password, the server displays the Getting Started page, as shown in 

Figure 1-3. 


1.1.1 Logging into a Server with Multiple Organizations 

If the administrator has configured your server to use the multi-tenancy feature, it supports multiple 
organizations. Each organization has its own private area for storing files and resources. The default Login 
dialog for a multi-tenant server has an additional field: Organization. The left side of Figure 1-2 shows this 
field. Enter the ID or alias of your organization. For example, enter the ID of the default organization: 

organization_l. 

You don’t have to enter the organization ID each time you log in. The first time you log in, include the 
organization ID in your login URL, as shown on the right side of Figure 1-2. Bookmark the URL and use it for 
subsequent log ins. The Organization field does not appear in the dialog when you specify it in the URL. 

http://<hostnanne>:8080/jasperserver-pro/login.htnnl 


TIBC^ Jaspersoft 


http://<hostnanne>:8080/jasperserver-pro/login.htnnl? 

orglD=organization_1 


Organization: 

organizal:ion_l| 


TIBC® Jaspersoff 


User ID: 


User ID: 


Password: 


Password: 


Show locale St time zone 


Show locale time zone 


Login 


Login 


Need help logging in? 


Need help logging in? 


Figure 1-2 Login Methods for Multiple Organizations 

The supemser account does not specify an organization because it is the system-wide administrator. If the 
Organization field appears in the Login dialog when you log in as supemser, leave it blank. If you try to log 
in as supemser with an orgID in the URL, the server returns an error. 
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1.2 The Getting Started Page 

From the Getting Started page, you can quickly access the most frequently used features of the server. 


Recent Items 

m 3.1 Sales Metrics 
Last Thursday at 1:11 PM 

(T> 5. Top Performers 
Last Thursday at 1:11 pm 

(h) 09. Customer Detail Report 
Last Thursday at 1:11 PM 

(!) 4. Product Category KPls 
Last Thursday at 1:11 pm 

^ 09. Store Segment Performance 
Last Thursday at 1:11 PM 

(h) 14. Stop Light KPI 
Last Thursday at 1:11 PM 

(h) 14.WoridMap 

Last Thursday at 1:11 PM 

(t) 2. Performance Summary Dashboard 
Last Thursday at 1:11 PM 


Video Tutorials 
(►) Ad Hoc Views 

Reporting and Scheduling 
Dashboards 
Data to Analysis 
Domains 

(►) Jaspersoft 7 Video Playlist 

Popular Resources 

jf- Quick Start Guide 

Step-by-step instructions for getting started with 
Jasperfieports Server. 

Documentation 

All documentation for JasperReports Server is right here. 


Visualizations 



Ad Hoc Views 

Create visualizations for basic reporting and analysis. 


Reports 

View and format interaaive multi-page reports. 


+ Create 


o 


Dashboards 

Combine visualizations into single-page dashboard layouts. 


Data 



Data Sources 

Connect to a database or other data source. 
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Domains 

Define business views on Data Sources for use in visualizations. 


Admin 



Users and Settings 

Manage users and configure your server instance. 


<1 Admin Menu 


Figure 1-3 Getting Started Page 


1.2.1 Core Workflows 

The Getting Started page for standard users has multiple blocks that link to the core workflows of JasperReports 
Server, that may include some or all of the following options: 

• Ad Hoc Views - Select or create a visualization for basic reporting and analysis. 

• Reports - Create an interactive report from an Ad Hoc view, or select an existing report. 

• Dashboards - Combine related visualizations into a single-page layout, or select from existing layouts. 

• Data Sources - Select or define a connection to a database or other data source. 

• Domains- Add stmcture to your data source for use in a visualization. 

• Users and Settings - Configure your server instance and manage user settings. This block is visible only 
to users with administrator privileges. 

Each workflow block on the Getting Started page may contain buttons linking to pages or wizards to create 
related elements. The large icon in each workflow block is a button linking to a filtered repository list 
containing relevant items. Click these buttons, rather than the blocks themselves, to access these resources. Users 
with administrator access may have more of these options available to them. 
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1.2.2 The Getting Started Column 

On the left side of the page, there are two lists to help you locate and access relevant information and assets. 

• Recent Items - Includes links to up to 10 recently viewed repository items, such as reports. Ad Hoc 
views, and dashboards. 

• Video Tutorials - Includes links to video tutorials for various JasperReports Server features. 

• Popular Resources - Includes links to educational and support resources. 


1.2.3 Menu Items 

The menu items along the top of the Getting Started page are available from every page on JasperReports 
Server. n and the Library, View, Manage, and Create menus offer the options described in the table below. 


Menu 

Description 

n 

Returns to the Getting Started page. 

Library 

Displays a pared-down repository page that contains the Ad Hoc views, reports, and 
dashboards the currently logged-in user has rights to 

View 

• Search Results - Displays the repository of resources filtered by criteria selected in the 
Filters panel. 

• Repository - Displays the repository of files and folders containing resources, such as 
reports, report output, data sources, and images. 

• Schedules - Lists the reports that you have scheduled. 

• Messages - Lists system messages, such as an error in a scheduled report. 

Manage 

• Organizations - Opens the Manage Organizations page. 

• Users - Opens the Manage Users page. 

• Roles - Opens the Manage Roles page. 

• Server Settings - Opens the Server Settings | Log Settings page. 

Create 

• Ad Hoc View - Launches the Ad Hoc Editor for designing views interactively. 

• Report - Launches the Create Report dialog for creating a report based on an Ad Hoc 
view and a report template. 

• Dashboard - Launches the Dashboard Designer for laying out multiple reports with input 
controls, labels, and images. 

• Domain - Launches the Domain Designer for setting up a Domain. 

• Data Source - Launches the New Data Source page for specifying the attributes of the 
new data source. 


If you log in as an administrator, the Home page has additional options and menu items for managing users, 
roles, organizations, and settings, such as repository folder names. Administrator frmctions are documented in 
the TIBCO JasperReports Server Administrator Guide. The links to the Online Help, Log Out, and a search 
field appear on all JasperReports Server pages. For more information about searching, see ^‘Filtering Search 
Results” on page 17. 
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1.2.4 JasperReports Server Keyboard Shortcuts 

JasperReports Server provides keyboard shortcuts to help you navigate its web UI without the use of a mouse or 
other pointing device. These shortcuts are available on the Login page, the Home page, the Library Page, the 
Repository page, the Search Results page, and the interactive report viewer, allowing you to log in, move 
between major navigational elements of these page, select and open reports, and navigate tabular reports. 

Shortcuts include: 


Key 

Action 

Left Arrow 

Navigate left one column, cell, or item. 

Right Arrow 

Navigate right one column, cell, or item. 

Up Arrow 

Navigate up one row, cell, or item. 

Down Arrow 

Navigate down one row, cell, or item. 

Enter 

Select an item or navigate into an inner control. 

Escape 

Cancel an action or navigate out to an outer control. 

Tab 

Navigate to the next major region or form field. 

Focus moves from left to right. 


Note that, on some pages, the Shift key can also be used in conjunction with the arrow keys or Tab: 

• When used with the arrow keys. Shift multi-selects items, such as reports listed in the Library page. 

• When used with Tab, Shift changes the direction that focus moves from left to right to right to left. 

In addition, the web UI has improved compatibility with screen readers, which assist visually impaired users in 
using computers. The implementation follows the WAI-ARIA (Web Accessibility Initiative Accessible Rich 
Internet Applications Suite) technical specification, and has been certified for certain versions of JAWS (Job 
Access With Speech) with certain browsers: 

• Internet Explorer 8 with JAWS 14 

• Internet Explorer 11 with JAWS 16 

To further increase JasperReports Server's accessibility, we recommend that you enable the Easy Access theme, 
which increases color contrast and highlighting in the web UI. It can improve the user experience of those with 
visual impairment. For more information on themes, see the TIBCO JasperReports Server Administrator Guide. 


1.3 The Library Page 

The Library page offers a more focused view of the repository objects. It contains only the Ad Hoc views, 
reports, and Dashboards that the currently logged-in user has rights to view and work with. 

Click Library to view your Library list. 
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Library 



Sort By: 

Name Modified Date 

0 Name 

Description 

Type 

Created Date Modified Date 

01. Geographic Results by Segment 

Sample HTML5 multi-axis column chart from Domain showing S... 

Ad Hoc View 

April 28 

10/21/2014 

01. Geographic Results by Segment Re... 

Sample HTML5 multi-axis column chart from Domain showing S... 

Report 

April 28 

9/24/2014 

02. Sales Mix by Demographic 

Sample HTML5 Spider Line chart from OLAP source 

Ad Hoc View 

April 28 

11/24/2014 

02. Sales Mix by Demographic Report 

Sample HTML5 Spider Line chart from OLAP source. Created fr... 

Report 

April 28 

9/24/2014 

03. Store Segment Performance 

Sample OLAP chart with HTML5 Grouped Bar chart and Filter 

Ad Hoc View 

April 28 

10/21/2014 

03. Store Segment Performance Report 

Sample OLAP chart with HTML5 Grouped Bar chart and Filter. C... 

Report 

April 28 

9/24/2014 

04. Product Results by Store Type 

Sample Filtered Table Report Showing Multiple Measures 

Ad Hoc View 

April 28 

5/15/2014 

04. Product Results by Store Type Report 

Sample Filtered Table Report Showing Multiple Measures. Great... 

Report 

April 28 

5/15/2014 

05. Accounts Report 

Basic interactive Table Component report with Bookmarks Panel 

Report 

April 28 

4/17/2014 

05g. Accounts Report 

Basic interactive Table Component report with alternate color s... 

Report 

April 28 

10/3/2013 

05. Unit Sales Trend 

Sample HTML5 Time Series chart from Topic for Unit Sales dat... 

Ad Hoc View 

April 28 

4/25/2014 

06g. Profit Detail Report 

Sample report containing containing interactive HTML5 Chart a... 

Report 

April 28 

5/13/2014 

06. Profit Detail Report 

Sample report containing containing interactive HTML5 Chart a... 

Report 

April 28 

5/13/2014 


Figure 1-4 Library Panel 

From the Library page, you can: 

• Run and schedule reports 

• Open Ad Hoc views and generate reports from them 

• Run and edit dashboards 

• Run OLAP views 

All of these functions are available by right-clicking the item you want to work with and selecting an action 
from the context menu. 


1.3.1 Created vs. Modified Dates 

The Library table has two columns that refer to when the repository items were created and last modified. 

Generally, the created date will be earlier than the modified date. In some situations, however, the created date 

may be after the modified date. This can happen for one of two reasons: 

• When an existing report (A) is modified, then subsequently copied into a new report (B). In the Libraiy list, 
report B’s created date is the day it was created, but its modified date reflects the last time report A was 
changed. 

• An existing report is exported from one system and imported into another. In the Library list, the reports 
created date is the date it was imported into the new system, and the modified date is the date it was last 
modified in the original system. 


1.4 Browsing the Repository 

The repository is the server’s internal storage for reports, analysis views, and related files. The repository is 
organized as a stmcture of folders containing resources, much like a file system. However, unlike a file system, 
the repositoiy is stored as a private database that only JasperReports Server can access directly. 

To browse the repository, select View > Repository. From the repository page, you access the reports, themes, 
and other files stored on the server. You can browse the repositoiy contents that you have permission to view 
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by expanding icons in Folders. Click a folder name to view its contents. In Figure 1-5, you'll see the 
Repository page. 


Cl Folders 

Organization ^ 

Repository 

^ Run Eflii Open '-opy Cut 

Paste Delete 

Sort By: Name 

1 Modified Date 

Ad Hoc Components 1 
^ Ad Hoc Reports 1 

0 Name 

Description 

Type 

Created .. 

Modified ... 

H* Topics 1 

All Accounts Report 

All Accounts Report 

Report 

April 28 

April 28 

Analysis Components 

Cascading multi select topic 

Shows cascading input controls. Multi-select and ... 

Report 

April 28 

April 28 

^ Content Files 

Customers Report 

Parameterized Report with no default values for... 

Report 

April 28 

April 28 

^ Dashboards 

demo for adhoc 

Topic containing shipping costs for orders 

Report 

April 28 

April 28 

^ Data Sources 

1^ Domains 

Employees 

Employee List topic based on Employee List repo... 

Report 

April 28 

April 28 

^ Images 

foodmart data for crosstab 

foodmart data for crosstab 

Report 

April 28 

April 28 

Organizations 

il8n columns 

Columns are Internationalizable.<br>Default su... 

Report 

April 28 

April 28 

1^ Performance 

MDX example 

Example of topic with MDX query 

Report 

April 28 

April 28 

^ Reports 

Parameterized Report 

Parameterized Report 

Report 

April 28 

April 28 

1^ SuperMart Demo 
I^Temp 

Simple Domain Topic 

Simple example of Domain saved as Topic 

Domain Topic 

April 28 

April 28 

1^ Templates 

SuperMart Products 

Information about all of the products sold by Su... 

Report 

April 28 

April 28 

Themes SuperMart Stores 

Simple Topic. Good for trying calculations (sales... 

Report 

April 28 

April 28 


Figure 1-5 Repository Folders Panel 


1.5 Searching the Repository 

You can search the entire repository, subject to permissions, or narrow the search using filters. Filters restrict a 
search by name, who changed the resource, type of resource, date of the resource, and schedule. 


1.5.1 Searching the Entire Repository 

To search the repository, select View > Search Results. The search results page appears. Instead of only 
viewing resources by folder, use intuitive search criteria, such as who modified the resource and when, to find 
pinpoint resources. 

On the search results page, use either the Filters panel or Search field to find resources. The search results page 
displays results of searches and filters. 
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Repository 


Filters 


Sort By: Name Modified Date 


V Access Status 

0 Name 

Description 

Type 

Created... 

Modifie... 

• All available 

01. Geoeraohic Results bv Sesment 

Sample Multi-axis column chart from Domain sh... 

Ad Hoc View 

July 15 

10/16/2019 

Modified by me 

01. Geographic Results by Segme... 

Sample Report containing hyperlinks and a map 

Report 

July 15 

10/17/2019 

Viewed by me 

02. Sales Mix by City 

Sample Spider chart from Domain data source a... 

Ad Hoc View 

July 15 

8/28/2019 

V File Type 

02. Sales Mix by City Report 

Sample Spider Line Report created from an Ad H... 

Report 

July 15 

8/28/2019 

• All types 

03. Store Segment Performance 

Sample Gauge Chart with multi-select filter fro... 

Ad Hoc View 

July 15 

10/11/2019 I 

Reports 

03. Store Segment Performance... 

Sample Gauge Report Created from an Ad Hoc V... 

Report 

July 15 

10/11/2019 

Content resources 

04. Product Results by Store Type 

Sample Filtered Table Report Showing Multiple... 

Ad Hoc View 

July 15 

8/28/2019 

Ad Hoc views 

04. Product Results by Store Typ... 

Sample Filtered Table Report Showing Multiple... 

Report 

July 15 

1 

8/28/2019 

Dashboards 





1 

OLAP views 

05. Accounts Report 

Basic interactive Table Component report with ... 

Report 

July 15 

8/28/2019 

Domains 

05. Unit Sales Trend 

Sample HTML5 Time Series chart from Topic for... 

Ad Hoc View 

July 15 

10/11/2019 

Data sources 

06. Profit Detail Report 

Sample report containing containing interaaive... 

Report 

July 15 

8/28/2019 

Deprecated reports 

06. Sales Mix by Gender 

Sample HTML5 percent bar chart from a Topic s... 

Ad Hoc View 

July 15 

10/11/2019 

N/ Accessed Date 

07. Brand Sales Analysis 

Sample HTML5 Scatter Chart providing multi-lev... 

Ad Hoc View 

July 15 

10/15/2019 

• Anytime 

07. Revenue Detail Report 

Sample report containing containing interactive... 

Report 

July 15 

8/28/2019 

Today 

08. Key Performance Metric Trend 

Sample HTML5 Dual-axis column-line chart sho... 

Ad Hoc View 

July 15 

10/11/2019 

Yesterday 

08. Unit Sales Detail Report 

Sample report containing containing interaaive... 

Report 

July 15 

8/28/2019 

Past week 

09. Customer Detail Report 

Sample report with multiple charts, interaaive t... 

Report 

July 15 

8/26/2019 

Past month 

09. Store Segment Performance 

Sample HTML5 Bubble Chart with basic user def... 

Ad Hoc View 

July 15 

11/24/2014 

v Schedule Status 

1. Supermart Dashboard 

Sample Dashboard containing filter pop-up. Das... 

Dashboard 

July 15 

10/16/2019 

• Any schedule 

10. Calculated Fields and Measures 

18 Sample Calculations 

Ad Hoc View 

July 15 

6/10/2016 

Scheduled 

10. Performance By Store Type 

Sample report with Donut Pie Charts and crosst... 

Report 

July 15 

10/11/2019 

Scheduled by me 

11. Sales By Month Report 

Sample multi-panel report 

Report 

July 15 

10/16/2019 

Not scheduled 

11. Top 5 Products by City 

Sample from Domain data source with nested to... 

Ad Hoc View 

July 15 

9/4/2019 


Figure 1-6 Search Results Page 
To search all resources in the repository: 

1. Select one of these filters: All available, Modified by me, or Viewed by me. 

2. Click the icon in the search field to clear the search term if there is one. 

3. Select All types, as shown in Figure 1-6. 

4. Click P. 

The search results appear listing files that your user account has permission to view. Click a resource in the 
list to view it or right-click a resource to see what functions are available from the context menu. 

The server remembers your settings on the Search Results page, so the most commonly needed resources remain 
visible when you return to the page. 
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1.5.2 Filtering Search Results 

0 

If you enter a search term and click ^ at the top of any server page, the server doesn’t use filters. The search 
uses these default settings: 

• Include subfolders 

• Start at the top-most folder visible to the user 

• Search for reports, report outputs, OLAP views, or other resources 

• Sort alphabetically by name 

P 

If you click View > Search Results and click ^ on the search results page, the server uses the filters you set 
in the Filters panel. 

In Figure 1-7, you can see the results of a search for the term “account” using the filters All available and All 
types. 


Repository 


Q Filters 

account 

X Q. 

Sort By: Name 

Modified Date 

V Access Status 

© Name 

Description 

Type 

Created ... 

Modifie... 

• All available 

05. Accounts Report 

Basic interactive Table Component report with B... 

Report 

July 15 

8/28/2019 

Modified by me 

20.1 Account List 

Sample Report used for basic Visualize.js demo 

Report 

July 15 

5/16/2014 

Viewed by me 

All Accounts Report 

All Accounts Rep>ort 

Report 

July 15 

July 14 

V File Type 

Employee Accounts 

List of Accounts per Employee 

Report 

July 15 

July 14 

• All types 

SugarCRM Sample Analysis View 

Sample SugarCRM Analysis View; Sales Performa... 

OLAP View 

July 15 

July 14 

Reports 

SugarCRM Sample XMLA Analysis .. 

. Sample SugarCRM Analysis View (XMLA); Sales Pe... 

OLAP View 

July 15 

July 14 


Content resources 

Figure 1-7 Search Field and Search Results 

The search term you enter in the search field isn’t cleared automatically. To clear the search term, click the 
^ icon in the search field. 


You refine a search using filters. For example, filters can help you find your most recently viewed reports. You 
can set each filter independently. You can set the following types of filters: 

• User 

• Resource 

• Access time 

• Scheduled report 

The user filter has the following settings: 


Filter Setting 

Description 

All Available (default) 

All resources. 

Modified by me 

Selects only resources that were last modified by the user who’s logged in. 
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Filter Setting 

Description 

Viewed by me 

Selects only resources that were run and viewed by the user who’s logged in. This 
filter not only applies to visualization types, but also to resources that are included in 
reports such as images. 


The resource type filter has the following settings: 


Filter Setting 

Description 

All types (default) 

All resources. 

Reports 

Displays only reports, both JRXML reports and Ad Hoc reports. 

Report outputs 

Displays only the output from reports that were scheduled or run in the background. 
Report output can be any of the supported export types, such as HTML and PDF. 

Dashboards 

Displays only dashboards. 

OLAP views 

Displays only analysis views (if you implement Jaspersoft OLAP). 

Domains 

Displays only Domains. 

Data sources 

Displays only data sources. 


The access time filter has the following settings. All times are relative to the user’s effective time zone: 


Filter Setting 

Description 

Any time (default) 

All resources. 

Today 

Resources viewed or modified since the previous midnight. 

Yesterday 

Resources viewed or modified during the previous day ending at midnight. 

Past week 

Resources viewed or modified during the past 7 days, including today. 

Past month 

Resources viewed or modified during the past 30 days, including today. 


The scheduled report filter has the following settings: 


Filter Setting 

Description 

Any schedule (default) 

All resources. 

Scheduled 

Only reports that have scheduled jobs. 

Scheduled by me 

Only reports that have jobs scheduled by the currently logged in user. 

Not scheduled 

Only reports that don’t have scheduled jobs and all other resource types. 


Remember these do's and don'ts when searching for resources: 
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• Do use word fragments. 

• Do search for the display name or part of the display name of a resource. 

• Do search for words or fragments in the description of a resource. 

• Do use multiple words. 

• Don’t search for folder names. 

• Don’t enter quotes around terms or symbols between terms. 

• Don’t worry about using upper- or lower-case letters in search terms. 


6 Using Repository Resources 

After finding a resource in the repository, naturally you want to do something with it. Options are: 

• Click the name of a report to mn and view it. 

• Right-click the name of a resource to access other operations on the context menu, for example Edit or 
Open in Designer. Items appear on the context menu according to your permissions. 

• Click anywhere in the row except the resource name to select a resource. Ctrl-click anywhere in the rows to 
select multiple resources. Use the context menu or buttons above the results list: Run, Edit, Open, Copy, 
Cut (move), or Delete. If the button is unavailable, the resource doesn’t support the operation or you don’t 
have permission for the operation. For example, the Open button is available when you select a dashboard 
or an Ad Hoc report if you have permission to write to it. 

You might also need permission to access the folder or dependent file, such as an image, of a resource. For 
example, to schedule a report, you need to have read/write/delete permission on the folder where server 
saves the report output. For more information about permissions, see the TIBCO JasperReports Server 
Administrator Guide. 

These two icons may appear in the Repository panel: 

• ^ indicates that the report has saved options for its input controls. Click the ^ icon to list the saved 
options. For more information, see ‘‘Running a Report with Input Controls or Filters” on page 71. 

• indicates that the report is scheduled to mn or is mnning in the background. Click this icon to view the 
list of jobs scheduled for the report. For more information, see “Scheduling Reports and Dashboards” on 
page 77. 


7 Moving Folders 

If you have read permission on folders and resources, you can copy and cut them from one folder and paste them 
to another if you have write permission on the destination folder. The server pastes all contents of the folder 
into the new location. 

You can drag-and-drop the objects instead of using the paste menu item. Move folders one at a time. You can 
move other resources in batches. 



Relocated objects inherit permissions from the destination folder, losing the permissions in place before 
the move. To change permissions on an object, set the permissions explicitly. 


To move folders and resources by cutting and pasting: 

1. Log into the server as a user who has these permissions: 

• Read permission on the folder or resource to move 
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• Write permission on the destination folder 

For example, log in as joeuser (use the password, joeuser). 

2. Click View > Repository. 

3. In the Folders panel, right-click Reports > Samples and select Add Folder. 

4. In the Add Folder dialog, enter a name, such as Financial Reports, and click Add. 

The Financial Reports folder appears as a subfolder of Samples and inherits Joe User’s default permissions 
(read-write-delete) on the parent folder. 


O Folders 

EUj Organization 

Ad Hoc Components 
EUj Additional Samples 
El i Analysis Components 
El-j Content Files 
EUj Dashboards 
EUj Reports 

EUj Interactive 


SB Samples 


ELj Financial Reports 


Figure 1-8 New Financial Reports Folder 

5. The Financial Reports folder deserves a more prominent location. Move it up one level: 

a. In Folders, right-click Financial Reports, and select Cut. 

b. Right-click Reports, and select Paste. 

The Financial Reports folder now appears in Reports at the same level as Samples. 



You can relocate a folder, subject to permissions, anywhere in the repository with one exception: The 
server doesn’t support copying and pasting a folder to the same location. If the Paste command is 
disabled when you right-click a destination folder, you don’t have write permission on the folder. 


.8 Sorting the Repository List 

To change the order of the list of reports and other resources, use the Sort By controls: 

• Click Name to sort alphabetically (A at the top). This is the default sort order. 

• Click Modified Date to sort by the latest modified time and date (most recent at the top). 
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This section describes functionality that can be restricted by the software license for JasperReports 
Server. If you don’t see some of the options described in this section, your license may prohibit you from 
using them. To find out what you're licensed to use, or to upgrade your license, contact Jaspersoft. 


A Jaspersoft dashboard displays several reports in a single, integrated view. A dashboard can include input 
controls for choosing the data displayed in one or more dashlets, and custom dashlets that point to URLs for 
other content. By combining different types of related content, you can create appealing, data-rich dashboards 
that quickly convey trends. 


0 2. Performance Summary Dashboard 


BC CA DF Guerrero 

-N ^ -N - 


Jalisco 




OR Veracruz WA 

Yucatan Zacatecas 

Date: Monday July 06, 2020 03:54 pm PDT 

'' ' ^ 


.•mi 'K 

% 



Figure 2-1 Sample dashboard 

This chapter contains the following sections: 

• Overview of the Dashboard Designer 

• Viewing a Dashboard 

• Creating a Dashboard 

• Editing a Dashboard 
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• Tips for Designing Dashboards 


.1 Viewing a Dashboard 

You can view a dashboard if you have the proper permissions. The following procedure walks you through 
opening one of JasperReports Server's samples, the Supermart dashboard. 

To view the Supermart dashboard: 

1. Log in as user demo, using the password demo. 


Passwords are case-sensitive. You must use lowercase when you type demo. 


The Supermart Top View dashboard opens in the dashboard viewer. 


SupGrnriart Top ViOW performance summary Dashboard Sales Metrics Dashboard Expense Metrics Dashboard Inventory Metrics Dashboard 



Figure 2-2 Supermart Dashboard Example 

2. Click one of the USA gauges. 

3. Select USA, then click Close to change the data displayed. 

The two dashlets with Country data update to display data for USA only. 



You can click on the funnel icon to select one or more countries from a filter panel. 


4. Click on Sales Metrics Dashboard. 

A new dashboard opens. The Sales Metrics Dashboard includes reports on sales by region, state, and city. 

5. Click on the Back button to return to the Supermart Dashboard. 

6. When done, click View > Repository to go to the repository page. 
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If a dashboard does not appear when you click on its name in the repository, it may already be open 
in another window or tab of your browser. 


If you have the proper permissions, you can easily switch from viewing a dashboard to editing it. 


To edit the Supermart dashboard: 

1. Open the Supermart dashboard in the dashboard viewer. 

2. Click the Viewing button on the title bar and select Editing from the drop-down list. 

3. Edit the dashboard by adding, removing, resizing, or dragging content. 

For more information about working with dashboard content, see ^‘Creating a Dashboard” on page 37. 

T and select Save Dashboard. To 

create a new version of the dashboard, select Save Dashboard As and specify a new name. 


.2 Overview of the Dashboard Designer 

The Dashboard Designer is a web-based UI for embedding reports. Ad Hoc views, and other BI objects into a 
single, interactive space. You can compile dashboards that include pre-existing elements, such as reports and 
views, and create new charts, tables, and crosstabs from your data sources directly from the designer. 

Each element on your dashboard is called a Dash let. Dashlets have unique names and resource IDs, and 
editable properties that vary depending on the Dashlet type. 

Your permissions to access the repositoiy may limit the content you can add and the location where you can 
save the dashboard. 

This section includes: 

• The Dashboard Designer Interface 

• Dashlets and Dashboard Elements 

• Previewing a Dashboard 

• Dashboard Properties 

• Dashlet Properties 

• Parameter Mapping 

,2.1 The Dashboard Designer Interface 

The following figure shows the basic layout of the Dashboard Designer. 
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O New Dashboard 

Q Available Content tT 

II. Chart 
r Crosstab 


® Web Page 
H Image 

V Existing Content : 

Cl 


9 01. Geographic Results b... 
(h) 01. Geographic Results b... 
S' 02. Sales Mix by City 

02. Sates Mix by City Report 
S 03. Store Segment Perfor... 
© 03. Store Segment Perfor... 
S 04. Product Results by St... 
© 04. Produa Results by St... 
© 05. Accounts Report 


© 06. Profit Detail Report 
S 06. Sales Mix by Gender 
S 07. Brand Sales Analysis 
© 07. Revenue Detail Report 
S 08. Key Performance Met... 
© 08. Unit Sales Detail Report 
© 09. Customer Detail Report 
S 09. Store Segment Perfor... 
^ 10. Calculated Reids and... 


© 10. Performance By Store... 
© 11. Sales By Month Report 
11. Top 5 Products by City 
© 12. Promotion Details Re... 




P 

Drag items here to create dashlets. 


Figure 2-3 The Dashboard Designer Ul 

The Dashboard Designer UI includes the following panels: 

• Available Content. From here, you can drag content onto the Dashboard Canvas. This panel includes the 
following sections: 

• New Content, which lists the content elements you can create for your dashboard. 

• Existing Content, which lists the Ad Hoc views and reports you can access from the Repositoiy. 

• Filters, which lists all filters associated with any resource added to the dashboard. 

• Toolbar Buttons. See table below for details. 


Icon 

Name 

Description 

ISI. 

Save/Save As 

Hover cursor over icon to open a menu of save options. 

4s 

Undo 

Click to undo the most recent action. 


Redo 

Click to redo the most recent undone action. 

ry 

Undo All 

Click to revert the dashboard to the most recently saved state. 


Parameter Mapping 

Click to open the Parameter Mapping dialog. See Parameter 
Mapping for more information. 


Dashboard Prop¬ 
erties 

Click to open the Dashboard Properties box. See Dashboard 
Properties for more information. 


Show/Hide Grid 

Click to display or hide a grid. 
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Icon 

Name 

Description 

T 

Show/Hide Filter 
Dashlet Pop-up 

Click to display or hide a filter pop-up window. This button only 
appears when you enable filter dashlet pop-ups in Dashboard 
Properties. 


• Dashboard Canvas. This is where you create and edit your dashboard. It includes the following sections: 

• Title Bar, which displays the name of the dashboard (in the figure above, the name is "New 
Dashboard"). It also includes the Editing/Viewing button, which allows you to switch between 
editing the dashboard and displaying it as viewed by the end user. 

• Main Creation Area, where you build your dashboard. Drag elements from the Available Content 
panel here to get started. 


.2.2 Dashlets and Dashboard Elements 

Each element added to your dashboard is called a Dashlet. 

To add a Dashlet to your dashboard, simply select a content element and drag it onto the dashboard canvas. 
Certain content, such as charts and crosstabs, open an embedded Ad Hoc editor, which is the same editor used 
to create Ad Hoc views. See ‘‘Overview of the Ad Hoc Editor” on page 91 for more information. 

Dashlets can include the following elements, which you can access from the Available Content panel: 

• New Content: 

• Chart: Allows you to create a chart using an embedded Ad Hoc editor. 

• Crosstab: Allows you to create a crosstab using an embedded Ad Hoc editor. 

• Table: Allows you to create a table using an embedded Ad Hoc editor. 

• Text: A free-form text entry field. Use free text items to add titles and instmctional text to the 
dashboard. 

• Web Page. Any URL-addressable web content. The dashboard can point to web content. 

• Image: An image from the repository or that is accessible by a web address URL. For example, you 
might include a dashlet that displays your corporate logo. The logo's image file can either be in your 
repository or on the server of your corporate website. 

• Existing Content: Reports and Ad Hoc views accessible to you. 

• Filters: If a dashlet you include on the dashboard is designed to use input controls or filters, you can add 
that capability to the dashboard. The server maps input controls to one or more dashlets. 

• Title Bar: You can enable a title bar in the Dashlet Properties dialog box. The title bar includes the 
following elements: 

• The Dashlet name, as entered in the Dashlet properties. 

• Dashlet toolbar, which can contain the following: 


Icon 

Name 

Description 

M 

Maximize 

Click to open the dashlet as a larger view. 




Refresh 

Click to refresh the dashlet. 
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Icon 

Name 

Description 

IT* 

Export 

Click to export the dashlet and save the output to your computer. 

See “Exporting Dashboards and Dashlets” on page 51 for more 
information. 


For more advanced Fmctionality, you can access dialog boxes that let you edit the overall appearance of your 
dashboard, modify the hmctionality of your dashlets, and create mappings between your dashboard input 
controls and your dashlets. 


2.3 Previewing a Dashboard 

You can preview your dashboard in display mode to see how it will appear when an end-user views it. 

To preview a dashboard: 

1. Click the Editing button and select Viewing from the drop-down list. The dashboard opens in display 
mode. 

2. To close the preview and return to the Dashboard Designer, click the Viewing button and select Editing 
from the drop-down list. 

2.4 Dashboard Properties 

You can view and edit the basic appearance of all dashlets on your dashboard, and determine the refresh 
settings, through the Dashboard Properties. 

To view and edit the Dashboard Properties: 

A 

1. On the dashboard toolbar, click ^ to open the Dashboard Properties window. 
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Dashboard Properties 


Canvas Sattings: 


Backgrou nd Color: #F 5 F 5 F 5 


U setcy^om-size rn pixels: 12 

?S0 by 800 

Dashlet 

U show Filter Dashlet 

U show borders 

Oyter margin in pixels: 

Inner padding in pixels: 

:as pop-u 

4 

1 

ip window 

Title bar text color: #i 

566666 



Title bar backgroy nd color: 

TRANSP 


ToolbafSetlinfS: 

U Show a port button 

fiefrash Sattlngs: 

U Auto-r-efnesh dashboard contents 


Refresh lnten.'al: 




15 


Seconds ^ 


Apply 


OK Cancel 


Figure 2-4 Dashboard Properties 

2. Edit the Canvas Settings, if needed: 

• Background Color: Select the color of the dashboard’s background. 

• Set custom size in pixels: Select when you want the dashboard to be displayed at a specific width 
and height instead of dynamically resizing based on the browser window. Enter the desired width and 
height of the dashboard. 

3. Edit the Dashlet Settings, if needed: 

• Show filter dashlet as pop-up: Select when you want the filter dashlet to appear as a pop-up 
window instead of a dashlet pinned on the dashboard. 

• Show dashlet borders: Select or deselect this to show or hide the thin lines around each dashlet. 


TIBCO Software Inc. 


27 

































TIBCO JasperReports Server User Guide 


• Dashlet outer margin in pixels: Enter the desired width, in pixels, of the margins between dashlets. 

• Dashlet inner padding in pixels: Enter the desired width, in pixels, of the padding inside each 
dashlet. 

• Title bar text color: Select the text color for the title bars of all of the dashboard's dashlets. 

• Title bar background color: Select the background color for the title bars of all of the dashboard's 
dashlets. 

4. Edit the Toolbar Settings, if needed: 

• Show Export Button: Select or deselect to show or hide the Export button in the dashboard viewer. 

5. Edit the Refresh Settings, if needed: 

• Auto-refresh dashboard contents: Select or deselect this to enable or disable automatic refresh for 
your content. 

• Refresh Interval: Enter the number of minutes or seconds between each content refresh, using the text 
entiy and drop-down menu. 


.2.5 Dashlet Properties 

You can view and edit basic information and appearance for each dashlet on your dashboard using the Dashlet 
properties. For some dashlets, you can also create parameters which you can then map to in Parameter Mapping. 
The available properties vary based on the type of dashlet you are working with. 

To view and edit the Dashlet properties: 

1. Right-click on the dashlet and select Properties to open the Dashlet Properties window. The Hyperlinks 
tab is available for Ad Hoc-based charts and charts created inside the dashboard, as well as text and image 
dashlets. A Formatting tab is available for text dashlets. 

2. Click Apply to view the changes, OK to accept the changes, and Cancel to discard the changes. 
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2,2,5.1 Basic Properties for Charts, Crosstabs, Tables, Reports, and Ad Hoc Views Dashlet 


Dashlet Properties 


Basic 


Hyperlinks 


Dashlet Name: 


05. Unit Sales Trend 


Resource ID: 

0 5_U n it_S ales_Tre n d 

Source Ad Hoc View: 

/ p u b I ic/S am pi es/Ad_H □ c_Vi e ws/05_Ur it_S a I es_Tren d 

Show/Hide Dashlet Elements: 

Q show title bar 

CD show refresh button 
Q Show maximize button 
CD Show export button 
Q Show Visualization Selector button 

Refresh Settings: 

CD Auto-reffesh dashlet contents 
Refresh Interval: 


Apply 


OK Cancel 


Figure 2-5 Basic Tab Properties 

• Dashlet Name: Editable field for the displayed dashlet name. 

• Resource ID: Non-editable ID taken from the original dashlet name. 

• Source Data: Non-editable path of the source data. 

• Show/Hide Dashlet Elements: Select or deselect to show or hide the title bar, which includes the dashlet 
name, refresh button, export button, and maximize button. You can also choose to show or hide the 
Visualization Selector button. 

• Scale to Fit: Use the drop-down menu to determine how the element is scaled in the dashlet. Scale to Fit is 
available for dashlets for tables, crosstabs, reports, and existing Ad Hoc view tables and crosstabs. Scale to 
Fit is not available for charts or existing Ad Hoc view charts. 

• Refresh Settings: Select or deselect to enable or disable auto-refresh, and use the text entry and drop¬ 
down menu to set the time between each content refresh. 
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2.2.5.2 Properties on the Hyperlink tab 


Dashlet Properties 


Basic Formatting Hyperlinks 


TeKt Hyperlinks: 

Q Enable text hyperlinks 
Action: 

I Update page 

Parameters: 


Name 


r arameters... 


Value 


Add New Parameter 


Apply 


OK Cancel 


Figure 2-6 Hyperlinks Tab Properties 


The Hyperlinks tab is available for Ad Hoc-based charts and charts created inside the dashboard, as 
well as text and image dashlets. 


• Enable hyperlinks: Select or deselect to enable a hyperlink for the dashlet. 

• Action: Select link behavior for this dashlet: 

• Update page: Select this option to update the dashboard's contents when a user clicks on a link in the 
dashlet. 

• Open new page: Select this to have the dashlet open a web page or report, dashboard, or an Ad Hoc 
view in the repository in a new browser tab or window when a user clicks on the dashlet. Click 
Browse to select a resource from the repository. 
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You can link directly to a web page using http: syntax: 

http://en.Wikipedia.org/wiki/$P{Customer Country} 

A repository URL must begin with repo :, for example, 

repo:/public/Samples/Ad_Hoc_Views/05._Unit_Sales_Trend 

You can add a parameter to a hyperlink for a web page, dashboard, or report. Parameters are not 
available for Ad Hoc views. See 2.4, “Specifying Parameters in Dashlets,” on page 44 for more 
information about adding parameters to hyperlinks. 

• Replace page: Select this option to replace the current dashboard page with a web page or report, 
dashboard, or an Ad Hoc view in the repository when a user clicks on the dashlet. Click Browse to 
select a resource from the repository. The syntax for links and parameters is the same as the Open new 
page option. 

If the dashlet replaces the page with an Ad Hoc view, it will open in the Ad Hoc View Designer. A 
Back button appears on the toolbar after the dashlet opens a report or dashboard that will take you 
back to the previous dashboard. 

• Available parameters: If you want to add a parameter in the hyperlink, use a name in this list to have 
Parameter Mapping create the link to the parameter automatically. 

• Add New Parameter: For text and image dashlets, you can define a parameter to include in the hyperlink. 
Click the Add New Parameter button and enter the parameter's name and value in the new table row. 
Click ^ to save the new parameter. 


Parameters: 


Name Value 





n/ X 


Figure 2-7 Adding a New Parameter to a Dashlet 

• Map Parameters: When you add a parameter, click this button to save and close the Dashlet Properties 
window and open Parameter Mapping. See Parameter Mapping for more information. 
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2.2.5.3 Basic Properties for Text Dashlets 


Dashlet Properties 


easic Formatting Hyperlinks 


Dashlet Name: 


Resource ID: 
Text 



OK Cancel 


Figure 2-8 Basic Tab for Text Dashlets 

• Dashlet Name: Editable field or the displayed dashlet name. 

• Resource ID: Non-editable ID taken from the original dashlet name. 

• Text: Editable field for the text displayed in the dashlet. 

2.2.5.4 Formatting Properties for Text Dashlets 



The Formatting tab is only available on text dashlets. 
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Dashlet Properties 


Basic 


Forma ttirg 


Hyperifnks 


Formatting: 

scale to Fit: 


None 


Font: 


Arial 


Size: 

12 


Style: 


B / U 


Arial 


8 

Arial Black 


9 1 

Arial Narrow 


10 

Courier 


11 

Courier New 


_12_1 

Georgia 


14 

Tahoma 


16 

Times New Roman 


18 

Verdana 


20 



22 



24 



26 



28 



36 



48 



Background Color: 











TRANSP 







Te^t color: 



[3^h let Formatting 


OK 


Cancel 


Figure 2-9 Formatting Tab for Text Dashlets 

• Scale to Fit: Use the drop-down menu to determine how the text is scaled in the dashlet. This overrides 
the specified font size. 

• Font: Use the selection lists and buttons to set the font, font size, font style, and alignment. 

• Background Color: Select the color of the dashboard's background. 

• Text Color: Select the color for the text displayed in the dashlet. 

• Show Borders: Select or deselect to show or hide the dashlefs border. If you select to show the dashlefs 
border, you can choose the border's color. 
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2.2.5.5 Basic Properties for Web Page Dashlets 


Dashlet Properties 

Dashlet Name: 

Wiki 

Resource ID: 

Web_Page 

Web Page Address [URL): 

htt p ://e n . w \ki pe d i a . org/w i ki/S P{St ore Co u ntr^--} 


Show/Hide Dashlet Elements: 

Q Show title bar 

Q Show refresh button 
Q Show maximize button 
Q Show scroll bars 

Refresh Settings: 

Q Aoto-reffesh dashlet contents 

Refresh Interval: 


Apply 


OK Cancel 


Figure 2-10 Basic Tab for Web Page Dashlets 

• Dashlet Name; Editable field for the displayed dashlet name. 

• Resource ID: Non-editable ID taken from the original dashlet name. 

• Web Page Address (URL): Editable field for the URL displayed in the dashlet. 

• Show/Hide Dashlet elements: Select or deselect to show or hide the title bar, which includes the dashlet 
name, refresh button, and maximize button. 

• Show scroll bars: Select or deselect to show or hide scroll bars. 

• Refresh Settings: Select or deselect to enable or disable auto-refresh, and use the text entry and drop¬ 
down menu to set the time between each content refresh. This setting overrides refresh properties set at the 
dashboard level. 
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2.2.5.6 Basic Properties for Image Dashlets 


Dashlet Properties 


Basic 


Hyperlirks 


Dashlet Name: 


Image 


Resource ID: 

Image 

webAddress/Reposltory URI: 

Browse... 

vVeb address must start with http or https 

Bhciw/Hrde Dashlet Elements: 

1 I showtrtlebar 

show refresh buttoni 
show maxrmize button 
V, show bonders 

Border Co lor: 

#D0D0D0 


Beale to Fit: 
Width 


Apply 


OK 


Cancel 


Figure 2-11 Basic Tab for Image Dashlets 

• Dashlet Name: Editable field for the displayed dashlet name. 

• Resource ID: Non-editable ID taken from the original dashlet name. 

• Web Address/Repository URI: Editable field for the location of the image displayed in the dashlet. This 
can include parameters. Click Browse to select an image from the repository. 

• Show/Hide Dashlet elements: Select or deselect to show or hide the title bar, which includes the dashlet 
name, refresh button, maximize button, and dashlet borders. If you select to show dashlet borders, you can 
choose the border color. 

• Scale to Fit: Use the drop-down menu to determine how the image is scaled in the dashlet. 
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2.2.5.7 Properties for Input Control Dashlets 


Filter Properties 

Filter Name: 

Store Country 


Resource ID: 
Store_Co untry 

Filter Label: 



Figure 2-12 Input Control Dashlet Properties 

• Dashlet Name: Editable field for the displayed dashlet name. 

• Resource ID: Non-editable ID taken from the original dashlet name. 

• Show/Hide Dashlet buttons: Select or deselect to show or hide the Apply button or Reset button. 

• Position of dashlet buttons: Use the drop-down menu to select bottom or right. 


.2.6 Parameter Mapping 

Parameter Mapping helps you refine your filters by letting you specify which dashlets and which parameters are 
affected by a filter. 


To open Parameter Mapping: 

1. Open a dashboard with filters, such as the Sales Dashboard created in Creating a Dashboard, in the 
Dashboard Designer. 


2. Click 


to open Parameter Mapping. 


Parameter Mapping 


Source Dashlet 

Filter/Parameter 

Dashlet Affected Filter/Parameter Affected 





Country 

1 04. Product Results by Store ▼ | | Country 

u 

+ 

lin 

Filter Group 

Department 

1 16. Interactive Sales Report ▼ | | Product_Department 

u 

+ 

mi 


Type 

1 16. Interactive Sales Report ^ | | Product_Family 

'1 

•f 

m 


Create New Filter 


OK 
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Figure 2-13 Parameter Mapping for the Sales Dashboard 

Parameter Mapping displays the filter-to-dashlet mapping, and includes the following columns and buttons: 

• Source Dashlet, the name of the dashlet where the filter originates. Can also display Filter Group 
(multiple filters in a single dashlet) or Manually Created Filter (filter created using Parameter Mapping, 
as described below). 

• Filter/Parameter, the name of the filter. 

• Dashlet Affected, with a dropdown menu including all dashlets that can be affected by that filter. 

• Filter/Parameter Affected, with a dropdown menu including all parameters associated with the 
selected dashlet in the Dashlet Affected column. 

• Add button ^, used to add additional dashlet/parameter combinations to a filter. 

• Delete button DD, used to delete a dashlet/parameter combination. 

From Parameter Mapping, you can add, delete, or edit an existing dashlet/parameter combination, and create a 
new filter to add to the dashboard. 

To add a filter using Parameter Mapping: 

1. Open a dashboard with filters, and open Parameter Mapping as described above. 

2. In the filter row you want to add the new filter to, click A row containing new affected dashlet and 
filter/parameter dropdown menus appears. 

3. Using these new line-items, select the dashlet and parameter combination you want to apply to the 
dashboard. 

4. Click OK to apply and save or Cancel to discard your changes. 

To delete a filter using Parameter Mapping: 

1. Open Parameter Mapping. 

2. In the filter row you want to delete, click DD . The filter row disappears from Parameter Mapping. 

To create a new filter via Parameter Mapping: 

1. Open Parameter Mapping. 

2. Click Create New Filter. A new row is added to the manager. 

3. In the Filter column, enter a name for the new filter. Click outside the text box to apply the name. 

4. Click ^ and select the dashlet and parameter combination you want to apply to the new filter. 

5. Click OK to apply and save, or Cancel to discard the new filter. 

To delete a newly-created filter: 

1. In Parameter Mapping, click DD in the filter row you want to delete. The Dashlet Affected and 
Filter/Parameter affected dropdown menus disappear. 

2. Click DD again in the row you want to delete. The Filter row disappears. 

3. Click OK to apply and save, or Cancel to discard the new filter. 

.3 Creating a Dashboard 

This section describes the creation of a simple dashboard. 
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To add a report or Ad Hoc view to a dashboard, you must have permission to view those elements. 


To create a simple dashboard: 

1. Click Create > Dashboard. The Dashboard Designer appears, displaying the list of available content and 
the canvas. 

2. In the Existing Content section of the Available Content panel, find report 16. Interactive Sales Report. 

3. Click and drag the report onto the Dashboard Canvas. 


O New Dashboard 


Q Available Content 

III Chart 
r Crosstab 


T Tew 
® Web Page 
Hlthage 

V Existing Content i 

Cl 

9 06. Sales Mix by Gender 
2 07. Brand Sales Analysis 
(Ij) 07. Revenue Detail Report 
2 OS.KeyPerfomnanceMet... ■ 
© 08. Unit Sales Detail Report I 
© 09. Customer Detail Report I 
^ 09. Store Segment Perfor... I 
^ 10. Calculated neldsand... I 
© 10. Performance By Store... I 
© 11. Sales By Month Report 
^ 11. Top 5 Products by City 
© 12. Promotion Details Re. .. 
©14. World Map 


© 17. Report Workbook 
© 20.1 Account List 
© 20.2Qties 
^ 20.3 SalesPerCIty 
© 20.3 SalesPerCItyReport 
© 20.6 Store Details 
S' ADV for Dashboard with P. .. 
© All Accounts Report 
© Analysis of Produn Sales.. 



Figure 2-14 Dragging report onto Dashboard Canvas 

4. In Available Content, find 04. Product Results by Store Type Report. 

5. Click and drag the report onto the canvas, until the left half of the Interactive Sales Report turns blue. 

The Product Results by Store Type Report appears on the canvas, next to the Interactive Sales Report. Both 
report dashlets are sized to fit side-by-side on the canvas. 

6. Right-click the Product Results by Store Type Report and click Properties. 

7. Use the Scale to Fit dropdown to select Dashlet. 

8. Click OK. The resized Product Results by Store Type Report now displays the entire crosstab in the dashlet. 

9. Click and drag the report 05. Accounts Report onto the canvas, until the lower half of the Interactive Sales 
Report turns blue. 

The Accounts Report is placed under the Interactive Sales Report, and both dashlets are resized to fit on the 
right half of the canvas. 

it 

10. In the Dashboard Designer toolbar, click ^ to open the Dashboard Properties dialog. 

11. Deselect Show borders under Dashlet Settings and click OK. 

In Figure 2-15 you can see how the dashboard canvas looks at this point. 
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p. * m 

04. Product Results by Store Type Report 
a 4 Page 1 ^ of 514 ► 


Store Sales 2019 Store Cost 2019 


Steady HCL Nasal 

Hermanos Broccoli 
Modell Pumpernickel 
Bread 

Vltelrus Meriot Wine 

Red Wing Bees Wax 

Candles 

Big City Canned 


Clams 

Club Jack Cheese I 

Just Right Rice Soup I 
PigTait Frozen Com t 
Golden Ice Cream I 
Just Right Canned 


1155 

10.32 


Fort West Chocolate 
PigTail Grape 


Musial White 
Chocolate Bar 
Horatio Beef Jerky 


1296 
10 29 


16. Interactive Sales Report 

4 Page 1 of 20 ► 


Product Transaction Summary Report 


Product Family 

Food 

Product 

Produce 

Product Category 

Vegetables 


High Top Onions 
High Top Summer Squash 
Tell Tale Summer Squash 
Tri-State Shitake Mushrooms 



• Sales 
9 Cost 


05. Accounts Report 

a < Page 1 of 47 ^ H 


Accounts 07/08/20 ASPERSOFT 



Name 

Phone 

Address 


1 Burnaby, Canada 



1 

Souza-Quick Construction Group 

699-555-8963 

3752 Hamilton a 

2 

Suffin-Cleary Engineering, Ltd 

367-555-1366 

3753 Forest Way 

3 

L & E Gillmore Communications Partners 

293-555-9531 

1983 Santa Cruz 

4 

N & 0 Garner Electronics, Inc 

472-555-1111 

9052 Montgomery 

5 

Orona-Warmack Transportation, Inc 

259-555-5742 

165 Schenone Court 

6 

D & Z McLaughlin Electronics, Ud 

602-555-9145 

661 Miller Ave. 

7 

Q & P Dodd Telecommunications Company 

910-555-8441 

5684 San Marino a. 


Figure 2-15 Simple Dashboard Canvas with three reports 


12. Click the Editing button and select Viewing to preview the dashboard. 

The end user view of the dashboard appears. 

13. Click the Viewing button and select Editing to return to the designer 

14. Click LJ T then select Save Dashboard. 

15. In the Save As window, change the default name, New Dashboard to Sales Dashboard and locate a 
folder, such as the /Dashboards folder. 

16. Click Save. 


.3.1 Adding New Content 

In addition to pre-existing reports and Ad Hoc views, you can create content for your dashboard directly from 
the Dashboard Designer, including: 

• Charts 

• Crosstabs 

• Tables 

• Text 

• Web page links 

• Images 

2.3.1.1 Adding Charts, Crosstabs, and Tables 

The Dashboard Designer includes an embedded Ad Hoc Editor, which allows you to create charts, crosstabs, 
and tables for your dashboard without leaving the designer environment. 
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Any chart, crosstab, or table you create within the Dashboard Designer is available only on the current 
dashboard; otherwise, they hinction like standard Ad Hoc Editor-created versions of these elements. They are 
saved as an Ad Hoc view and placed in a dashlet on your dashboard. 

To add a new chart, crosstab, or table to your dashboard: 

1. In the New Content section of the Available Content panel, click and drag the type of element you want 
to add to your dashboard (Chart, Crosstab, or Table) onto the dashboard canvas. 

The Ad Hoc Editor opens, and the Select Data dialog appears. 

2. Browse to or search for the data source you want to use. 

• Click for a tree view of the files. 

■ 

m 

• Click ■“ for a list view of the files. 

• Use the text search field to locate a specific data source. 

3. Depending on your selected data source, the remaining steps may vaiy. Follow the displayed instmctions. 
for more information about this process, see 5.1.1, “Ad Hoc Sources: Topics, Domains, and OLAP 
Connections,” on page 93. 

4. When you complete the data source selection process, click OK. The Ad Hoc Editor opens. 

The embedded Ad Hoc Editor works just like the standard editor. For information on working with the 
editor, see Chapter 5, “Working with the Ad Hoc Editor,” on page 91. 


Library View - 

Manage - 

Create - 

superuser Help Log Out 

- 


123 Sales 
123 Unit Sales 

123 SKU 
123 SRP 

123 Gross Weight 
123 Net Weight 
123 Units per Case 


New Ad Hoc View 

Q Topic: SuperMart Pro.. 


P 


0 ^ III 

1 1 Fields 

• 

Columns 





Rows 



vnc Department 





'nc Category 




Click to add a title 

■be Sub Category 

- 




H Measures 

: 








P 


Add a measure to continue. 


About TIBCO JasperReports Server 


Copyright €) 2005-2019 TIBCO Software Inc. 


Figure 2-16 Embedded Ad Hoc Editor 

5. When you finish creating your view, click S to save. 
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6. In the Save to Dashboard dialog, enter a dashlet name and click Save. The dashlet is added to your 
dashboard. 

2.3.1.2 Adding Text 

You can add a text field dashlet for titles and instmctional text. 

To add a text dashlet: 

1. In the New Content section of the Available Content panel, click and drag the Text item onto your 
dashboard. The Dashlet Text window opens. 

2. Enter the text you want to appear on your dashboard. 

3. Click OK. The dashlet is added to your dashboard. 

Edit the dashlet name and font appearance by opening the Properties dialog. See “Dashlet Properties” on 
page 28 for more information. 

2.3.1.3 Adding a Web Page 

You can add a dashlet to display a web page on your dashboard. 

To add a web page dashlet: 

1. In the New Content section of the Available Content panel, click and drag the Web Page item onto 
your dashboard. The Dashlet URL window opens. 

2. Enter the URL you want to appear on your dashboard. 

3. Click OK. The dashlet is added to your dashboard. 

Edit the dashlet name by opening the Properties dialog. See “Dashlet Properties” on page 28 for more 
information. 

2.3.1.4 Adding an Image 

You can add a dashlet to display an image, such as a corporate logo, on your dashboard. 

To add an image dashlet: 

1. In the New Content section of the Available Content panel, click and drag the Image item onto your 
dashboard. The Dashlet URI window opens. 

2. Enter the URI for the image you want to appear on your dashboard. Use the repo : syntax for images in 
your repository. 

3. Click OK. The dashlet is added to your dashboard. 

Edit the dashlet name by opening the Properties dialog. See “Dashlet Properties” on page 28 for more 
information. 


.3.2 Adding Controls to a Dashboard 

The Interactive Sales Report was designed to be mn with input controls. When you add a report that has input 
controls to a dashboard, the controls don’t appear until you explicitly add them, one-by-one. The controls can 
either be added directly to the dashboard as a dashlet or accessed from the toolbar as a pop-up window. When 
the report mns, dashboard users provide input using the control. Data based on the user input appears in the 
dashboard. For example, using the input control, you select Mexico. The report on the dashboard shows orders 
from Mexican companies. 

Keep these points in mind when viewing a dashboard that has input controls: 
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• An input control may appear as a text field, a drop-down, a check box, a multi-select list box, or a calendar 
icon. 

• If one of the dashlets in a dashboard does not refer to an input control, that dashlet does not update when 
you change that input control’s value. Only dashlets that use the input control reflect the change. 

• The ^ ^ buttons on the toolbar allow you to undo and redo recent changes made to the 

dashboard, including changes using an input control. 

• If the ^ button appears on the toolbar, then the dashboard was set up to display input controls as a pop¬ 
up window instead of a dashlet. Click the button to view the controls. 

To add controls as a dashlet: 

1. If the Sales Dashboard created in Creating a Dashboard is not open, locate the /Dashboards folder in the 
repository. Right-click the dashboard name and select Open in Designer from the context menu. 

The Sales Dashboard appears in the designer, as shown in ^‘Simple Dashboard Canvas with three 
reports”, and the input controls available appear in the Filters section of the Available Content panel. 

2. In the Filters section, expand the 16. Interactive Sales Report folder. 

The input controls associated with the Interactive Sales Report appear. 

3. Drag the Country input control onto the canvas, and place it above the Product Results by Store Type 
dashlet. 

The Country input control and its label appear above the Product Results by Store type report on the 
canvas. 

4. Drag the Product Family and Product Department controls onto the Country input control dashlet. These 
input controls are added to the same dashlet. Resize the dashlets as needed to view all of the input controls. 

5. Click LJ w and select Save Dashboard, then click the Editing button and select Viewing to preview the 
dashboard. 

6. Click in the Country text box to display the available countries. In this input control, you have the 
following options: 

• The three countries: Canada, Mexico, and USA. 

• ^ All, which selects all available values in the input control. 

• ^ None, which deselects all available values in the input control. 

• ^ Invert, which deselects any selected values, and selects the unselected values. 

7. Use the options to select Mexico from the values list, and click Apply at the bottom of the dashlet. The 
data displayed in the Interactive Sales Report changes, but is not updated in the other reports, as they do 
not have an input control named Country. 

8. Click the Viewing button and select Editing to return to the Dashboard Designer. 

You can also change the labels, or display names, of individual input controls and filters within a dashlet. 

To rename an input control or filter: 

1. With the Sales Dashboard open in the Dashboard Designer, right-click Product Family in the input control 
dashlet, and select Properties. The Filter Properties dialog opens. 

2. Change the Filter Label from Product Family to Type, and click OK. 

3. Right-click the Product Department input control and select Properties. Change the Product Department 
filter label to Department, and click OK. The input control labels are updated. 
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Parameter Mapping 


Source Dashlet 

Filter/Parameter 

Dashlet Affected Filter/Parameter Affected 





Country 

1 04. Product Results by Store ▼ | | Country 

▼ 1 

+ 

ini 

Filter Group 

Department 

1 16. Interactive Sales Report ▼ | | Product_Department 

'1 


fS 


Type 

1 16. Interactive Sales Report ^ | | Product_Family 

'1 

+ 

m 


Create New Filter 


OK 


Figure 2-17 Parameter Mapping for the Sales Dashboard 
To add controls as a pop-up window: 

1. With the Sales Dashboard open in the Dashboard Designer, click 

2. Select Show filter dashlet as pop-up and click OK. 


to open Dashboard Properties. 


The input controls dashlet disappears from the dashboard and ^ appears on the toolbar. This button is 
also displayed when you're viewing the dashboard. 

3. Click LJ w and select Save Dashboard, then click the Editing button and select Viewing to preview the 
dashboard. 

4. Click ^ to view the filter pop-up window. 

Like the dashlet, selecting the options in the pop-up changes the data displayed in the Interactive Sales 
Report. 


Click I 


I to close the filter pop-up window. 


Click Viewing button and select Editing to return to the Dashboard Designer. 


.3.3 Refining a Dashboard’s Layout 

After completing the layout, refine the look and feel of the dashboard. 

To refine the dashboard’s layout: 

1. If it isn’t open, locate the Sales Dashboard you created in Creating a Dashboard, typically in the 
/Dashboards folder. 

2. Right-click the dashboard name, select Open in Designer from the context menu 

3. When the dashboard opens in the designer, click Preview. 

The end user’s view of the dashboard appears. 

4. In the Country field, select a new value. 

The reports do not update because the dashboard includes the Apply button. 

5. Return to the Dashboard Designer and on the Country filter dashlet, right-click and select Properties. 

6. Deselect Show Apply button, and select Show Reset button. 

7. Click Apply. 
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The dashlet's Apply button disappears, and the Reset button appears. 

8. Reposition the Reset button to the right side of the dashlet using the Position of dashlet buttons drop¬ 
down menu. Click OK. 

9. Click Preview. The end user view of the dashboard appears. 

10. Change the value in the Country input control. The dashboard reflects the change immediately. 

11. Return to the Dashboard Designer and click Save > Save Dashboard. The dashboard is saved to the 
repositoiy. 


.4 Specifying Parameters in Dashlets 

You can add parameters to dashlet names, text dashlets, web page dashlets, image dashlets, and hyperlinks in 
chart dashlets. When you add a parameter, you must map a filter in the dashboard to the parameter. See 

Mapping parameters in Parameter Mapping for more information. 

Simple parameters: 

For text dashlets, web links, and dashboard names, use the syntax $P{parameter_name } to directly pass the 
parameter value to the web page. Examples: 

• In a text dashlet, enter the parameter in the Text box: 

Product Family: $P{Product Family} 

• In a web page dashlet or a web link in a chart dashlet hyperlink, enter the parameter in the Web Page 
Address (URL) text box: 

http://en.wikipedia.org/wiki/$P{Store Country} 

• In a repository or web URI for an image dashlet, enter the parameter, enter the parameter in the Web 

Address/Repository URI text box: 

repo:/public/Samples/Reports/$P{Store Country}/flag.png 

• Dashlet name: Enter the parameter in the Dashlet Name box: 

Unit Sales for $P{Product Family} 

For repository hyperlinks in a chart dashlet, use the syntax ?filter_in_target=$P{dashlet_param} . For 
example, the following link sets the c_country_l input control in the 05. Unit Sales Trend report to the value of 
a Store Country parameter in the dashlet. 

repo:/public/Samples/Reports/05._Unit_Sales_Trend?c_country_l=$P{Store Country} 



To find the correct name for a filter in a target resource, open the Dashboard Designer in a new 
window, and add the resource to the canvas. Then expand the resource's folder in the Filters panel 
and hover over the filter whose name you want to see. 


Parameters in multi-valued input controls: 

For multi-valued input controls, you can define a separator for the input control values: 

• For text dashlets, web links, and dashboard names, use the syntax $P{parameter_name ? "separator"}. The 
following example in a text box displays results like Product Family: Drink + Food: 

Product Family: $P{Product Family ? " + "} 

• For repository links in a chart or image dashlet, use the syntax ?$P{ "filter_in_target='b dashlet_ 
param, ? "&"}. For example, the following link allows multi-select with the c_countiy_l input control in 
the 05. Unit Sales Trend report: 
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repo:/public/Samples/Reports/05._Unit_Sales_Trend?$P{"c_country_l =", Store 
Country, "&"} 

When Mexico and USA are selected, this expands to the following link: 

repo:/public/Samples/Reports/05._Unit_Sales_Trend?c_country_l=Mexico&c_country_l=USA 

Auto-complete parameters 

When you type the $ symbol into a dashlefs text box, a drop-down list of available parameters is displayed. 
Select a parameter from the list or continue typing to narrow down the list of parameters. The auto-complete 
parameters feature is available for text fields, image link, and web links, but it is not available for the dashlet 
name field. 


Dashlet Text 

Text: 

$P{} _ 

Measures Categcrj $PiC-Guntry} with //ypeioEcks to the 

Customer State frori Pr^uct C^tegc-ry $P{CQu^tfy} with ih^perhnks to the 
Product Category Rf^uct Categvn -SPfQ&uutryJ- with Hypeihnks to the 
Measures Store Segment Pe:fbrw:^rDe with i*/periwks 
Country fr-c-c Store Segraent PerfbrrrBnDe with h^ypor'wks 
Store Type Store Segment PerformBnce with hfyperimks 

Figure 2-18 Text dashlet showing available parameters 

Mapping parameters in Parameter Mapping 

After you have created a parameter, create a mapping for it as follows: 

Mapping parameters in dashboard names and text, image, or web page dashlets: 

1. In the Dashboard Designer, click to open Parameter Mapping. 

2. In the filter row where you want to add the new filter, click A row containing new affected dashlet and 
filter/parameter dropdown menus appears. 

3. Using these new line-items, select the dashlet where you added a parameter, then select the parameter. 

4. Click OK to apply and save or Cancel to discard your changes. 

Mapping parameters in chart hyperlinks: 

To have JasperReports Server create a parameter mapping automatically: 

1. In the Dashlet Properties dialog box for your chart, use one of the names in the Available parameters list as 
the name of your parameter. 

2. Click OK to close the dialog box and create the mapping. 

To create a mapping in Parameter Mapping: 
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1. In the Dashlet Properties dialog box for your chart, click Create Links in Parameter Mapping... to open 
Parameter Mapping. 

2. In the filter row where you want to add the new filter, click A row containing new affected dashlet and 
filter/parameter dropdown menus appears. 

3. Using these new line-items, select the dashlet where you added a parameter, then select the parameter. 

4. Click OK to apply and save or Cancel to discard your changes. 

.4.1 Creating a Web Page Dashlet 

When working with Web Page dashlets in the Dashboard Designer, you can include a parameter reference in the 
dashlef s URL. The parameter references an existing filter in another dashlet, and uses that filter to display a 
specific web page relevant to the filtered information. 

The following example takes you through the steps for creating a simple dashboard in the Dashboard Designer, 
adding a sample chart with geographic filters, and creating a Web Page dashlet that displays a Wikipedia page 
for the country the sample chart is filtered on. 

First, create the simple dashboard: 

1. Log in to JasperReports Server as supemser. 

2. Click Create > Dashboard. 

The Dashboard Designer appears, displaying the list of available content and the canvas. 

3. In the Existing Content section of the Available Content panel, find report 08. Key Performance Metric 
Trend. 

4. Click and drag the report onto the Dashboard Canvas. Note that the Filters section now includes the 08. 
Key Performance Metric Trend folder. 

Next, add the filter input control to the dashboard: 

1. In the Filters section, expand the 08. Key Performance Metric Trend folder. 

The input controls associated with the 08. Key Performance Metric Trend report appear. 

2. Drag the Store Country input control onto the canvas. 

Now, add the Web Page dashlet with the parameter reference and add it to the filter: 

1. In the New Content section of the Available Content panel, click and drag the Web Page item onto 
your dashboard. 

The Dashlet URL window opens. 

2. Enter the following URL: 

http://en.wikipedia.org/wiki/$P{Store Country} 

3. Click OK. 

4. Right-click the dashlet and select Properties. 

5. Change the Dashlet Name to Wiki. 

6. Click OK. 

7. Click on the Ad Hoc menu to open Parameter Mapping. 

8. In the Store Country filter group, click 

A row containing the new affected dashlet and filter/parameter dropdown menus appears. 

9. In the Dashlet Affected column, select Wiki from the new Select dashlet... dropdown menu. 


46 


TIBCO Software Inc. 




Chapter 2 Working with Dashboards 


10. In the Filter/Parameter Affected column, select Store Country from the new Select parameter... dropdown 
menu. 

11. Click OK. 

Finally, preview the new dashboard functionality: 

1. Click the Editing button and select Viewing to preview the dashboard. 

2. Click in the Store Country text box to display the available countries. 

3. Select Canada from the values list in the Store Country input controls, and click Apply at the bottom of 
the dashlet. The data in the Key Performance Metric Trend report is updated to display only information 
about Canada, and the wiki dashlet displays the Wikipedia page for Canada. 

In Figure 2-19 you can see how the dashboard preview looks at this point: 


O New Dashboard ffl. ^ ^ 


Viewing 


Store Country 


Available: 3 
Search list... 


Canada 


Mexico 

USA 

✓ Select All X None E Invert 


Selected; 1 

Q. 


* ft 




A Not logged in Talk Contributions Create account Log in 


Wikipedia 

The Free Encyclopedia 


Article Talk Read View source View history | Search Wikipedia Q | 

Canada ★ S 

From Wikipedia, the free encyclopedia Coordinates ^ 60 °N iio°w 


Apply 


Main page 
Contents 
Current events 
Random article 
About Wikipedia 
Contact us 
Donate 

Contribute 

Help 

Cnmmiinrtv nnrtal 


This article is atx)ut the coutitry. For other uses, see Canada 
(disambiguation). 


Canada is a country in 
the northern part of North 
America. Its ten 
provinces and three 
territories extend from 
the Atlantic to the Pacific 
and northward into the 





Figure 2-19 Dashboard with web page parameters 

4. Click the Viewing button and select Editing to return to the Dashboard Designer. 

5. Click ISIT, then select Save Dashboard. 
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6. In the Save As window, change the default name, New Dashboard to Key Performance Metric Trend 
Dashboard and locate a folder, such as the /Dashboards folder. 

7. Click Save. 

.4.2 Adding a Hyperlink to a Chart Dashlet 

When working with chart dashlets in the Dashboard Designer, you can specify a link that opens when a user 
clicks the dashlet. You can optionally include a parameter which references an existing filter in another dashlet, 
and uses that filter to display a specific web page relevant to the filtered information. 

The following example takes you through adding a hyperlink to the chart dashlet created in 2.4.1, “Creating a 
Web Page Dashlet,” on page 46. The example also shows how to add a parameter to a hyperlink. 

First, open the dashboard: 

1. If the Key Performance Metric Trend dashboard created in 2.4.1, “Creating a Web Page Dashlet,” on 
page 46 (above) is not open, locate the /Dashboards folder in the repositoiy. Right-click the dashboard 
name and select Open in Designer from the context menu. 

The Key Performance Metric Trend dashboard appears in the designer. 

Create a chart hyperlink: 

1. Right-click on the 08. Key Performance Metric Trend dashlet and select Properties.... 

The Dashlet Properties dialog box opens. 

2. Click the Hyperlinks tab. 


Dashlet Properties 

Basic I I Hyperlinks |_ 

Chart Hyperlinks; 

| 5 ^J Enable chart hyperlinks 
Action; 

I Open new page ^ | 

Web Address/Repository URI; 

re p 0 ; / p u b I i c/S a m p I es/ Repo rts/ 04._P ro d u ct_R es u lts_by_Sto n 
Repository URI m ust start with repo: 

Available parameters; 

Measures 
Customer Gender 
Product Family 
Store Country 

Create Links in Filter Kanager... 


Apply 


Figure 2-20 Hyperlinks tab in Dashlet Properties 

3. Click Enable chart hyperlinks to select it. 

4. Choose Open new page from the Action menu. 
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The Web Address/Repositoiy URI entiy bar is displayed. 

5. Enter repo:/public/Samples/Reports/04._Product_Results_by_Store_Type_Report for the Web 

Address/Repositoiy URL 


To see the report's path, hover over the report's name in the Existing Content pane. 


6. Click OK. 


Preview the new dashboard functionality: 

1. Click Editing button and select Viewing to preview the dashboard. 

2. Click the chart dashlet. 

The 04. Product Results by Store Type Report opens in a new tab. 

3. Return to the tab containing Key Performance Metric Trend dashboard and click Viewing button and select 
Editing to return to the Dashboard Designer. 

Add a parameter: 

1. Right-click on the Key Performance Metric Trend dashboard dashlet, select Properties..., and click the 
Hyperlinks tab. 

The Available Parameters area shows the parameters available in the chart. 

2. Modify the URL to add a parameter that provides a value for an input control in the target report: 

You need to know the correct name of the input control in your target report. In this case it is sales_ 

store_store_contact_store_country_l in the 04. Product Results by Store Type Report. 

Create a parameter. If you create a parameter name, it is helpful to use a name that is not used in 
Parameter Mapping. In this example, use LinkCountry. For more information about parameters, see 2.4, 
^‘Specifying Parameters in Dashlets,” on page 44. 

The link is as follows: 

repo:/public/Samples/Reports/04._Product_Results_by_Store_Type_Report?sales_ 

store_store_contact_store_country_l=$P{LinkCountry} 

If you use one of the names in the Available Parameters list, the mapping to the parameter is created for 
you. In this example, if you use store Country instead of LinkCountry, you do not need to create links 
in Parameter Mapping. 

This example does not show how to add support when more than one country is selected. For more 
information, see 2.4, “Specifying Parameters in Dashiets,” on page 44. 

3. Click Map Parameters. Click Yes when prompted. 

Parameter Mapping is displayed. 
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Parameter Mapping 


Source Dashlet Filter/Para meter Dashlet Affected Filter/Para meter Affected 

08. Key Performance Metric 

Trend 

Date 4 * 

Measures + 

Filter Group 

1 08. Key Performance Metric ’ ^ | | LinkCountry ^ | QD 

Store Country | 08. Key Performance Metric ' ^ | | Store Country ^ | QD 

1 Wiki ▼ 1 1 Store Country ▼ | + QD 


Create New Filter 


OK 


Figure 2-21 Parameter Mapping 

4. In the Store Country filter group, click 

A new row with affected dashlet and filter/parameter drop-down menus appears. 

5. In the Dashlet Affected column, select 06. Sales Mix by Gender from the new Select dashlet... dropdown 
menu. 

6. In the Filter/Parameter Affected column, select LinkCountry from the new Select parameter... dropdown 
menu. 

7. Click OK. 

Finally, preview the new dashboard functionality: 

1. Click Editing button and select Viewing to preview the dashboard. 

2. Click in the Store Country text box to display the available countries. 

3. Select Mexico from the values list, and click Apply at the bottom of the dashlet. 

4. Click the chart dashlet. 

The 04. Product Results by Store Type Report opens in a new tab. 

5. To verify that the parameter has been passed correctly, click in the 04. Product Results by Store Type 
Report. 

The Input Controls dialog box opens, with Mexico set. 

6. Return to the tab that contains your dashboard. 

7. Click Viewing button and select Editing to return to the Dashboard Designer. 

8. Click ISI T, then select Save Dashboard. 

.5 Editing a Dashboard 

You can edit a dashboard if you have the proper permissions. 

To edit a dashboard: 

1. Select View > Repository and search or browse for the Dashboard you want to modify. 

By default, the repository includes the /Dashboards folder where you can store dashboards. 
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2. Right-click the dashboard and select Open in Designer from the context menu. The designer appears, 
displaying the dashboard. 

3. Edit the dashboard by adding, removing, resizing, or dragging content. 

For more information about working with dashboard content, see “Creating a Dashboard” on page 37. 

T and select Save Dashboard. To 

create a new version of the dashboard, select Save Dashboard As and specify a new name. 


.6 Exporting Dashboards and Dashlets 

You can create a snapshot of a dashboard or dashlet and save it on your computer. Exporting a dashboard or 
dashlet requires the following: 

• The export button has been enabled for the dashboard or dashlet. See “Dashboard Properties” on page 26 
and “Dashlet Properties” on page 28 for more information. 

• Chrome/Chromium is installed on the computer hosting JasperReports Server. For information on 
configuring Chrome/Chromium for dashboards, see the System Configuration chapter in the TIBCO 
JasperReports Server Administrator Guide. 

To export a dashboard: 

1. Select View > Repository and search or browse for the Dashboard you want to export. 

2. Click the link to open the dashboard. 

3. Hover your cursor over for the dashboard or individual dashlet and select the export format from the 
drop-down list. 

The available formats are: 

• PNG (Dashboard only) 

• PDF 

• Excel (Paginated) (Dashlet only) 

• Excel (Dashlet only) 

• CSV (Dashlet only) 

• DOCX 

• RTF (Dashlet only) 

• ODT 

• ODS (Dashlet only) 

• XLSX (Paginated) (Dashlet only) 

• XLSX (Dashlet only) 

• PPTX 

4. Save the dashboard or dashlet in the export file format, for example PDF, or open it in the application. 


If you perform the export while a dashlet is reloading its 
box in the exported file. 


content, the dashlet will appear as a grayed-out 


6.1 Localizing Controls 

You can design dashboard controls to accommodate different languages. First, use the $R syntax to define 
prompts and static lists of values. Next, attach resource bundles to the report that contain translations of the 


TIBCO Software Inc. 


51 





TIBCO JasperReports Server User Guide 


prompts and lists of values. Finally, add the report to the dashboard. For more information about how to localize 
input controls, see ‘‘Localizing Reports” on page 204. 


.7 Tips for Designing Dashboards 

Charts and small crosstabs are best suited to dashboards. However, you can design table reports that work well 
in the dashboard. Such reports tend to be veiy narrow and are typically used with input controls to limit the 
number of rows they return. 

Keep reports small because dashboards typically contain more than one. In particular, reports shouldn’t be too 
wide, as horizontal room is always at a premium in a dashboard. The server strips margins from an Ad Hoc 
report when displaying the report on a dashboard. 

7.1 Input Control Tips 

When designing input controls for a dashboard, keep these guidelines in mind: 

• To pass a value to an external URL, the URL Parameter Name you give to the input control must match 
the name of a parameter that the URL can accept. The value of the input control must also be a value the 
URL can accept. The target URL is likely to have additional requirements and limitations. For example, the 
name of the parameter may be case-sensitive; in this case, the value you enter in the URL Parameter 
Name field is also case-sensitive. 

The input control must pass data that the URL can accept. Otherwise, the server may be unable to retrieve the 
correct data from the external URL. 


7.2 Time-Date Wildcards 

When creating dashlets, you can enter a wildcard into a text input field to display the current date or time: 

• $Date: Displays the current date in the Month Day, Year format. For example, January 15, 2 016. You 

can also customize how the date is displayed using the following parameters: 

• $Date{MM-DD-YYYY}. For example, January 15, 2016 is displayed as 01-15-2016. 

• $Date{DD/MM/YYYY}. For example, January 15, 2016 is displayed as 15/01/2016. 

• $Date{dddd MMMM DD, YYYY}. For example, January 15, 2016 is displayed as Friday January 15, 
2016. 

• $Time: Displays the current time in the 12 hour format with am/pm, but without the leading 0 for hours. For 

example, 1:25 pm. You can customize how the time is displayed using the following parameters: 

• $Time {HH:mm} . Displays the time in the 24 hour time format. For example, 1:25 pm is displayed as 
13:25. 

• $Time{hh:mm a}. Displays the current time in the 12 hour format with am/pm and the leading 0 for 
hours. For example, 01:25 pm. 

• $Time {HH : mm : ss }. Displays the current time in the 24 hour time format with seconds. For example, 
1:25:30 pm is displayed as 13:25: 30. 

• $Time{hh:mm: ss a} . Displays the current time in the 12 hour format with seconds, am/pm, and the 
leading 0 for hours. For example, 1:25:30 pm is displayed as 01:25: 30 pm. 

• $Time {HH: mm : ss z}. Displays the current time in the 24 hour time format with seconds and the time 
zone. The time zone is selected on the login page. For example, 1:25:30 pm in the Pacific Standard 
time zone is displayed as 13:25:30 PST. 
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• $Time {hh:mm: ss a z }. Displays the current time in the 12 hour format with seconds, am/pm, the time 
zone, and the leading 0 for hours. The time zone is selected on the login page. For example, 1:25:30 
pm in the Pacific Standard time zone is displayed as 01:25: 30 pm PST. 

The wildcards are available for text fields, image link, and web links, but it is not available for the dashlet name 
field. 

When you type the $ symbol into a dashlefs text box, a drop-down list with the time-date wildcards and other 
available parameters is displayed. Select the wildcard you want from the list or continue typing to narrow down 
the list. 


Dashlet Text 
Text: 


$P{ ... > 

$Date 
$Date{ ... > 

[ $Time 

$Tlme{ ... } 

Figure 2-22 Time-Date Wildcard Auto-complete 
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JasperReports Server makes it easy to mn reports. When you mn a report, it opens in the interactive Report 
Viewer. With the Viewer, you can personalize and refine the displayed report data. If the report has input 
controls, you mn the report with one set of data and then another. 

This chapter contains the following sections: 

• Overview of The Report Viewer 

• Running or Creating a Simple Report 

• Running a Fusion Chart 

• Running a Report with Input Controls or Filters 

The tutorials in this chapter and throughout this guide assume you’ve installed the sample data provided with 
the server. 


3.1 Overview of The Report Viewer 

The Report Viewer allows you to view a report, export content to various output formats, and apply formatting, 
sorting, and filters to control how the data is displayed. 

This section describes the functions available in the Report Viewer. You can find more detailed information 
about using this functionality throughout this chapter. 

To open a report in the Report Viewer: 

1. Locate your report in the library or repository. 

2. Click the report name, or right-click the report name and select Run. In the repository, you can also click 
the report row and select Run from the tool bar. The report opens in the Report Viewer. 

3.1.1 The Report Viewer Tool Bar 

The Report Viewer tool bar contains a number of controls for working with your report. These controls are 
described in Table 3-1. 
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Table 3-1 Report Viewer Tool Bar Icons 


Icon 

Name 

Description 


o 


Refresh 
report with 
latest data 

Click to refresh the report data from the data source. 

a 

First 

Click to jump to the first page of the report. 

< 

Previous 

Click to go to the previous page in the report 


Current 

Page 

Shows the number of the currently displayed report page. 

I 

L 

of 47 


► 

Next 

Click to go to the next page in the report. 


Last 

Click to jump to the last page of the report. 


Zoom Out 

Click to zoom out on the report. 


+ 


Zoom In 

Click to zoom in on the report 



Zoom 

Options 

Click this icon to open the Zoom Options drop-down menu. 

100% 




Search 

Enter your search term here to find a text string in your report. Click the 
drop-down menu to toggle search preference settings. 

1 search report 

P 

T 



< 


Search 

Previous 

Click to jump to the previous instance of the search term. 


► 


Search Next 

Click to jump to the next instance of the search term. 

Back 

Back 

Exits the Report Viewer and takes you to the previous screen. 

P 

Save 

Place the cursor over this icon to open a menu of save options. 
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Icon 

Name 

Description 

m 

Export 

Click to export the View into one of the available formats. 


Undo 

Click to undo the most recent action. 


Redo 

Click to redo the most recently undone action. 

f) 

Undo All 

Click to revert the report to its most recently saved state. 

m 

Input 

Controls 

Click to see the input controls applied to this report. For more 
information, refer to “Simpie input Controis” on page 71 . 

m 

Bookmarks 

Click to display the Table of Contents pane. This pane is available only 
on reports with enabled Bookmarks. 


3.1.2 Column Menu 

Reports that contain table components are enabled for user interactivity. Table components are defined in 
Jaspersoft Studio or from Ad Hoc Views. When a table is enabled for interactivity, column formatting, filtering, 
and sorting are managed from a menu displayed by clicking the column you want to apply changes to. These 
menu icons are described in Table 3-6. 


Table 3-2 Column Formatting Icons 


icon 

Name 

Description 


Formatting/Show column/Hide column 

Select Formatting to open the Format Column box. 

Select Show coiumn or Hide coiumn. 

V 

Column filters 

Click to open the Filter column box. 
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Icon 

Name 

Description 


Sort ascending 

Click to sort fields in the selected column in ascending 
order. 


Sort descending 

Click to sort fields in the selected column in ascending 
order. 

T 

Column size 

Click and drag this icon to make columns wider or 

narrower. 


3.1.3 Data Snapshots 

Some reports have an optional data snapshot feature enabled. A data snapshot is a cached copy of the data 
included in a specific report. Data snapshots allow you to access a report's data (including input control 
settings) without having to retrieve it from the data source, which in some cases can save a significant amount 
of time. 

When a report is opened in the Report Viewer, data is retrieved from the data snapshot. If the snapshot does not 
exist, then a live queiy is made to the data source. A snapshot is created when a report is saved from the viewer, 
or via the scheduler. The Report Viewer UI displays a date and time stamp that indicates when the report data 
was last refreshed with live source data. 


The system administrator can enable or disable the data snapshot feature. 


It should be noted that a report can have only one snapshot. For instance, if you edit and save a report that 
already has a snapshot associated with it, a new snapshot overwrites the previously-created snapshot. 


3.2 Running or Creating a Simple Report 

You can view and work on a report in the Report Viewer in a number of ways: 

• Running an instance of an existing report 

• Creating a new report from an existing Ad Hoc view 

3.2.1 Running a Simple Report 

This section describes how to mn a tabular report that lists account data. 

To run a report: 

1. Log into the server as an administrator, such as jasperadmin. 

2. On the Home page, click the large icon in the Reports block. 

The search results appear, listing your own files and other files that your user account has permission to 
view. If you log in as jasperadmin, 05. Accounts Report appears in the search results. 
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0 Filters 


Repository 



Sort By: Name 

1 Modified Date 

• All available 

Modified by me 

Viewed by me 

1 

All + Reports 

O Name 

Description 

Type 

Report 

Report 

Created ... 

May 7 

May 7 

Modified ... 

_____ 1 

03. Store Segment Performan... 

04. Product Results by Store ... 

Sample OI_AP chart with HTML5 Grouped Bar ... 

Sample Filtered Table Report Showing Multipl... 

4/25/2014 1 

5/15/2014 

All types 


1 05. Acxounts Report 

Basic interactive Table Component report with... 

Report 

May 7 

4/17/2014 1 

• Reports 


OSg. Accounts Report 

Basic interactive Table Component report with... 

Report 

May 7 

10/3/2013 

Report outputs 


06g. Profit Detail Report 

Sample report containing containing interactiv... 

Report 

May 7 

5/13/2014 

More choices... 


06. Profit Detail Report 

Sample report containing containing interactiv... 

Report 

May 7 

5/13/2014 



07g. Revenue Detail Report 

Sample report containing containing interactiv... 

Report 

May 7 

5/13/2014 


Figure 3-1 Search Results Listing 

3. To run a report, click the name of a report in the repository. For example, click 05. Accounts Report. The 
report appears, as shown in Figure 3-2. 


^ 05. Accounts Report Data refreshed 2019-09-23 at 12;56;07 O 

Back ISJ» ^ PI — 100% ▼ I search report C^ ▼ 

Accounts 09/23/19 ^^JASPERSOFT 


# Name Phone Address 


1 

Burnaby, Canada 



1 

Souza-Quick Construction Group 

699-555-8963 

3752 Hamilton Ct 

2 

Suffin-cleary Engineering, Ltd 

367-555-1366 

3753 Forest way 

3 

L & E Gillmore Communications Partners 

293-555-9531 

1983 Santa Cruz 

4 

N & o Garner Eiectronics, inc 

472-555-1111 

9052 Montgomery Avenue 

5 

Orona-Warmack Transportation, inc 

259-555-5742 

165 Schenone Court 

6 

D & Z McLaughlin Electronics, Ud 

602-555-9145 

661 MiHer Ave. 

7 

Q & P Oodd Telecommunications Company 

910-555-8441 

5684 San Marino Cr 

8 

F & X Wellington Communications Partners 

210-555-7617 

4055 Hitchcock 

9 

Ratdrff-Moss Elearonics, Ud 

721-555-7412 

4776 Kentucky Drive 

10 

Rosemont-McMenama Engineering, Ud 

678-555-1134 

6228 Meadowbrook Dr. 


Page [l [ of 47 ^ PP 


Figure 3-2 Output of the Accounts Report 


If you are running a report with multiple pages, the first page of the report appears before the entire report 
is loaded. You can begin scrolling through report pages as they load, as indicated in the pagination 
controls in the upper left corner of the Report Viewer. 


If you want to cancel loading the report before it is complete, click the Cancel Loading button that appears 
next to the pagination controls. 


.2.2 Creating a Report 

You can create a report directly from the Jaspersoft Server Home page. This method allows you to select an 
existing Ad Hoc view and generate a report from it, without going through the Ad Hoc Editor. 

To create a report from the Home page: 

1. On the Home page, click Create in the Reports block. The Create Report wizard opens. 

2. Select the Ad Hoc view you want to use as the basis for your report. 

3. Select a report template. To use a template other than the default, select Custom Report Template, click 
Browse and select the desired template. See 3.2.3, ^‘Report Templates,” on page 60 for more information. 
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4. Click OK. If asked, enter the input controls needed. See ^‘Using Input Controls” on page 161. 
You can now begin working with your report. 


2.3 Report Templates 

When you create a report, the Create Report wizard displays layout options for generating and exporting the 
report: 

• Default Report Template applies basic layout options to your report. This is usually the Actual Size 
template. 

• Custom Report Template allows you to browse to an existing template. JasperReports Server includes a 
number of templates are available by default, including: 

• A4 Landscape 

• A4 Portrait 

• Actual Size 

• Letter Landscape 

• Letter Portrait. 

Other report templates may be available. Report templates can be created in Jaspersoft Studio and uploaded 
to JasperReports Server. 

• Report Generator allows you to create a highly customized report design. This option is not often 
enabled. See your JasperReports Server administrator for more information. 

Most commonly, you will choose Default Report Template. 

3.2.3.1 Using Report Templates for PDF 

If you are exporting your report to PDF, choose your option based on the size of the output. 

• For most PDF exports, you can use Actual Size, which supports a maximum size of 14400px by 14400px. 

• For reports with an output height exceeding 14400 px, use a paginated report template that is wide enough 
for your report. For example, if you have a long report with width less than 842px, you can use the 
paginated A4 Landscape theme. A report designer can create additional custom templates in Jaspersoft 
Studio, contact your administrator for more information. 

• Reports with output width exceeding 14400 px will be tmncated in PDF. Redesign your report or use a 
different export format. 


.3 Getting New Perspectives on Data 

The report shown in Figure 3-2 was created using the Ad Hoc Editor. As this type of report mns, you can 
interact with it in the Report Viewer to visualize the data in different ways. Column formatting allows you to 
highlight certain columns and fields, and filtering and sorting report output on-the-fly can provide timely views 
of the data that answer your questions. For example, suppose you’re mnning the Accounts Report and want to 
know how many accounts have offices nearby. Highlighting the phone number column with red text and 
filtering it to show only accounts in your area code would reveal this data. 

3.1 Column Formatting 

You can customize the basie formatting of column headings and fields, using the Format Column dialog. Hover 
over ffl’' and click Formatting... The Format column dialog appears. 
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Figure 3-3 Format Column Dialog 

You can alter a column’s basic formatting or apply conditional formatting to a column. 


In longer reports, columns have floating headers. If your report extends past your browser frame, use the 
vertical scroll bar to move up and down the list. If you do not see a vertical scroll bar, try increasing the 
width of your browser window. 


This section discusses how to apply formatting to column headings and values. For information on conditional 
formatting, see ^‘Conditional Formatting” on page 62. 

Column formatting options include: 

• Text 

• Font type, size, and style 

• Background color 

• Font color 

• Text alignment 

To customize your column formatting: 

1. Run your report, so it opens in the Report Viewer. 

2. Click the column you want to format. 

3. Hover over and click Formatting... 

4. Click the Basic Formatting tab, and change the following options if needed: 

• Apply to - Select the part of the column you want to apply the formatting to. 

• Heading text - Type new heading text to replace the current text. 

• Font - Scroll through the menu to select a font. 

• Size - Scroll through the menu to select a font size. 

• Style - Cl ck to select Bold, Italic, or Underlined text. 

• Background Color - Click to open the background color picker, then click to select the background 
color. 

• Font Color - Click to open the font color picker, then click to select the text color. 

• Alignment - Click to select Left, Center, or Right alignment. 
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5. If needed, click Previous Column or Next Column to change the formatting for an adjacent column. 

6. Click OK. 


.3.2 Conditional Formatting 

The Report Viewer allows you to format column headings and fields, to highlight data that meets specific 
criteria. For instance, if you want to call out fields for store sales above $100,000, you can do so by applying 
text and background formatting to those stores that meet those numbers. 

With conditional formatting, you can apply the formatting options listed in “Column Formatting” on page 60. 
However, it is a slightly more complex process than applying formatting options to entire columns. This section 
describes those complexities, including: 

• Condition hierarchy 

• Condition button states 

• Applying conditional formatting 

3.3.2.1 Condition Hierarchy 

If you have multiple conditions applied to a single field, their order will affect how they fianction. Conditions 
are read and applied from bottom to top, and the topmost condition overrides the one(s) below. 

For example, imagine you have more than one condition applied to the same format element: red text for all 
stores over 20,000 square feet, and blue text for all stores over 30,000 square feet. As shown in “Condition 
Hierarchy Example” on page 62, placing the formatting mle for stores over 20,000 above the mle for stores 
over 30,000 causes the topmost mle to override the one below: 
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Figure 3-4 Condition Hierarchy Example 
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3.3.2.2 Condition Button States 

Because conditions higher up in the hierarchy can affect those below, the font style selection buttons each have 
three states: 

• Unchanged, which means it inherits the previous condition-based style, if any. 

• Set, which means the style is applied to text that meets the condition. 

• Not Set, which means the style is not applied to the text that meets the condition, and is removed if a 
conflicting condition lower in the conditional formatting hierarchy has marked that style as “Set”. 

By default, the buttons are in the “Unchanged” state. Clicking the buttons toggles you through the three states. 

See “Style Button States” for examples of the style button states. 


Table 3-3 Style Button States 



Unchanged 

Set 

Not Set 

Bold 


B 


■ 


E 


Italic 


/ 


■ 


/I 


Underline 


u 


■ 


n 



The background and font color pickers have buttons for similar states, but these states behave slightly 
differently: 

• Unchanged, which means the field inherits the previous condition-based color, if any. 

• Set, which means the color is applied to text or background of the field that meets the condition. 

• No Fill (background only), which means no color is applied to the background that meets the condition. 
Regardless of conditions lower in the hierarchy, the background inherits the table’s default color. 

Both have two buttons at the top of the window, along with the color selection boxes. 

You control these states through the background color picker and the font color picker windows, using the 
following buttons: 

• No Fill (background only), which applies the No Fill state described above. 

• Reset, which returns the text or background to the Unchanged state. 

• The color selection boxes, which apply the Set state. 

See “Color Picker Button States” for examples of the color picker button states. 
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Table 3-4 Color Picker Button States 



Unchanged 

Set 

No Fill 

Background Color 

Oi, 






<3^, 



Text Color 

A, 


A- 


N/A 


3.3.2.3 Applying Conditional Formatting 

You apply conditional formatting much like you do standard column formatting, as described in ^‘Column 
Formatting” on page 60 with the extra step of creating the condition by which the formatting is applied. 

To create a condition: 

1. Run your report, so it opens in the Report Viewer. 

2. Click the header or field of the column you want to format. 

3. Move your mouse over and click Formatting... 

4. Click the Conditional Formatting tab. The Conditional Formatting options appear: 



Figure 3-5 Conditional Formatting Tab 

5. In the Apply to box, select the part of the column you want to apply the formatting to. 

6. Click Add. This adds a line item in the Conditions List. 

7. Fill in the following information: 

• Operator: Use the drop down menu to define how the condition is compared to the column data. 

• Condition: Enter the condition criteria. 

• Format: Select the formatting applied to fields meeting the defined condition. Take care setting the 
button states, as described in ^‘Condition Button States” on page 63. 

8. Repeat if needed to add multiple conditions to a column. 

If you have multiple conditions, you may want to reorder them, to ensure they do not conflict with each 

other. Use the ^ and ^ to move conditions in the hierarchy. 
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9. If needed, click Previous Column or Next Column to change the conditional formatting for an adjacent 
column. 

10. Click OK. The condition is applied to the column. 

.3.3 Interactively Filtering Report Output 

If the report output contains more information than you want, interactively filter it to display just what you 
need. You conditionally filter report output by first selecting the column to use as a basis for filtering. Next, 
you enter a filter condition, then a value for comparison. The server compares each field of the column to the 
value that meets the condition. In Table 3-5 you can see the conditions available for each type of column: 
numeric, date, and text. 

Table 3-5 Interactive Filtering Conditions 


Numeric 

Date 

Text 

Equals 

Equals 

Equals 

Does not equal 

Is not equal to 

Is not equal to 

Greater than 

Is between 

Contains 

Greater than or equal to 

Is not between 

Does not contain 

Less than 

Is on or before 

Starts with 

Less than or equal to 

Is before 

Does not start with 

Is between 

Is on or after 

Ends with 

Is not between 

Is after 

Does not end with 


To interactively filter report data: 

1. As you mn the type of report shown in Figure 3-2, click the column you want to use for filtering the 
report. Continuing with the example in ^‘Running or Creating a Simple Report” on page 58, click the 
Phone column in the Accounts report. 

2. Click the . 

The Filter column dialog appears, as shown in Figure 3-6. By default. Show all rows is selected. 

3. To build your filter, click the radio button to select Show only rows where, 
the comparison operator drop-down and value entry box become active. 

4. Select a comparison operator from the drop-down. For example, select Starts with to compare phone 
numbers starting with certain numbers. 

5. Enter a value for comparison with the data in the column. For example, enter the area code: 4 08- 
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__ n 

Phone Starts with t 408- [ Filter ] 


Figure 3-6 Filter Column Dialog 

6. Click OK. 

The view of the report changes to show the filtered output. For example, now the Accounts Report only 
shows accounts in the 408 area code. 


(3 05. Accounts Report Data refreshed 2019-10-09 at 10:24:08 O 
Back ffl. (rI, ^ m 


+ 


search report 


5F 


Accounts 10/09/19 


^^JASPERSOFT 


# Name Phone V Address 

1 Colma, USA 

1 H & G Van Antwerp Machinery Corp 408-555-3003 4137 E St. 

2 La Mesa, USA 

1 G & N Cramer Communications Group 408-555-5009 6696 Adria Drive 

3 Marysville, USA 

1 R & Z Gilliat Communications, inc 408-555-4801 177 Bancroft Road 

4 Palo Alto, USA 

1 Mullins-Maes Construction Partners 408-555-6001 8722 East View Place 


Figure 3-7 Filtered Report Shows Only Accounts in Area Code 408 

A small star icon appears in the heading of the filtered column, to the right of the heading text. 

7. To clear the filter indicator and once again display all the accounts, reopen the Filter column dialog and 
select Show all rows, then click OK. 


.3.4 Interactively Sorting a Report 

You can also sort data in report output interactively. For example, you can sort the data alphabetically in 
ascending or descending order within each city listed in the Accounts Report. 


To interactively sort report output: 

1. As you mn the type of report shown in Figure 3-2, click the column you want to use for sorting the report. 
For example, click the Name column in the Accounts report. 


2 . 


Click ^ (sort ascending) or (sort descending). The report refreshes, and data appears sorted by the 

selected column in the selected order. In this example, for instance, if you select ^ , the grouped rows of 
data are sorted alphabetically in ascending order within each group. Row 1 of the Burnaby, Canada group 
is now D & Z McLaughlin Electronics, Ltd and row 1 of the Cliffside, Canada group is Abbott-Liff 
Electronics Holdings. 

The heading text in the column used to sort report data appears red, and the up or down arrow icon in the 
column header indicates that report output now appears in ascending or descending order, respectively. 


66 


TIBCO Software Inc. 














Chapter 3 Running Reports and the Report Viewer 


To change the sort order of the groups themselves, you have to modify the report query. 


3.5 Moving, Resizing, and Hiding Columns 

Columns are easily moved, resized, and hidden in your report. 

• To move a column, click the column you want to move, then drag the column left or right into the new 
position. The ^ indicates where the column is placed. 

• To resize a column, click the column you want to resize, then drag the ^ until the column is the size 
you want. 

• To hide a column, click the column you want to hide, then move your mouse over the and select 

Hide column. 


3.6 Sett! ng Output Sea le 

You can determine the display size for any report by using the report scaling options, located in the Report 
Viewer tool bar. 

• Click ^ to zoom in on the report. 

• Click — to zoom out on the report. 

• Click i I to open the Zoom Options drop-down menu, and select the percentage by which you 

want to increase or decrease the size of the displayed report. 


3.7 Using the Bookmarks Panel 

When working with a report that contains bookmarks, they are displayed in a floating panel. Using this panel, 
you can jump to designated sections of the report. 
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Bookmarks 

Beverly Hills 

Bremerton 

Burbank 

Burien 

Burlingame 

Chula Vista 

Colma 

Concord 

Coronado 

Corvallis 

Daly City 

Downey 

Edmonds 

El Cajon 

Everett 

Fremont 

Glendale 

Grossmont 

Imperial Beach 

Issaquah 

Kirkland 

La Jolla 

I ake IJswRnn 


0 


Figure 3-8 The Bookmarks Panel 


To display the Bookmarks panel, click 


in the Report Viewer tool bar. 


To jump to a bookmarked section of the report, click the name of the section in the Bookmarks panel. 


.4 Navigating the Report 

If your report has multiple pages, you can use the pagination controls to move through the report quickly. 

To navigate the published report: 

• Use at the top of the Report Viewer to navigate to the previous page. 

• Use ^ to navigate to the next page. 

• Use to go to the end of the report. 

• Use ^ to go to the beginning of the report. 

• If you know the number of the page you want to view, enter the page number in the Current Page indicator 
box. 
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.5 Exporting the Report 

To export the report: 

1. To view and save the report in other formats, click the Export button. 

2. Select an export format from the drop-down. The export options are listed in Table 3-6. 


Table 3-6 Export File Types 


Option 

Format Name 

Usage 

PDF 

Adobe Acrobat 

Choose a report template based on report size. Use the 
Actual Size report template for reports with dimensions less 
than or equal to 14400px by 14400px. See 3.2.3, “Report 
Templates,” on page 60 for more information. 

Excel (Paginated) 

XLS 

Not recommended for exporting most tables or crosstabs. 
Repeats headers and footers on each page. 

Excel 

XLS 

Ignores page size and produces spreadsheet-like output. 

CSV 

Comma Separated Values 

Characters outside the Latin 1 character set can cause the 
Excel spreadsheet to look unacceptable. Try saving the file 
and importing it using Excel's Import functionality. 

DOCX 

Word 

Do not export reports having more than 63 columns. In 
Microsoft Word, you cannot create tables having more than 

63 columns. 

RTF 

Rich Text Format 

Creates a large output file and, therefore, takes longer to 
export than PDF, for example. 

ODT 

OpenDocument Text 

For best results, minimize the number of rows and columns 
and make sure they don’t overlap. 

CDS 

OpenDocument 

Spreadsheet 

Same as ODT. 

XLSX (Paginated) 

Microsoft Open XML Format 
Spreadsheet 

Not recommended for exporting most tables or crosstabs. 
Repeats headers and footers on each page. 

XLSX 

Microsoft Open XML Format 
Spreadsheet 

Ignores page size and produces spreadsheet-like output. 

PPTX 

Microsoft PowerPoint 
Presentation 

Each page of report becomes a slide in the PowerPoint 
presentation. 


3. Save the report in the export file format, for example PDF, or open the report in the application. 
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.6 Running a Fusion Chart 

The JasperReports Server commercial editions support Fusion charting, and include the Maps Pro, Charts Pro, 
and Widgets Pro component libraries. 

Using the libraries, you can create visually appealing, animated, and interactive reports: 

• Maps Pro - Color-coded maps covering all countries and regions of the globe. 

• Charts Pro - Standard and stacked charts with animation and interactivity. 

• Widgets Pro - Non-standard charts such as gauges, hmnels, spark lines, and Gantt charts. 

These components are based on Fusion libraries and generate HTML5 output that is embedded in the HTML 
and PDF output. When a report containing a Maps, Charts, or Widgets Pro element is exported in a format other 
than HTML or PDF, the space used by the element remains blank. 

Flash is no longer recommended. 

For configuration information, see the TIBCO JasperReports Server Administrator Guide for more information. 

Fusion charts are created in Jaspersoft Studio Professional as JRXML reports and uploaded to the repository as a 
report unit. 

To find and run a chart example: 

1. In the repositoiy, locate the sample report 14. World Map. 

2. Click the report name to mn the report. 

3. In the Input Controls window, select Food as the product family you want to view sales trends for and 
click OK. The report appears, as shown in Figure 3-9. 



Figure 3-9 World Map Report with Flash Map 

4. To interact with the map, mouse-over any of the countries to see the hill country name and, when it has 
data, the value for that country. 
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5. On the map, click Canada to launch the Interactive Sales Report, displaying the information for Canada 
only. From there, you can modify the underlying report as needed. 

To upload JRXML reports, see “Adding Reports Directly to the Repository” on page 175. 


.7 Running a Report with Input Controls or Filters 

An input control are graphical widgets that filter the data that appears in a report. The perfect input control 
limits the data to what you want to see—and nothing more. When you mn a report based on a Domain Topic 
that defines a filter, the server can render the filter as an input control. The JasperReports Server interface uses 
"input controls," "filters," and "options" interchangeably. 

If your system administrator has enabled the data snapshot feature (described in “Data Snapshots” on page 58), 
it is important to note that the default input controls - that is, the input controls as defined when the original 
Jaspersoft Studio- or Ad Hoc View-based report is mn - will overwrite any changes made to them the next time 
you mn a report. For instance, suppose you mn a report, update the input controls, then save the report. At a 
later date, you mn a report from the Jaspersoft Studio or Ad Hoc View source again. That new report will 
replace the report you ran earlier, and your input control changes will be lost. 

To avoid this, save a version of the report with your selected data preloaded. That way, when subsequent reports 
are mn from the same source, they will not overwrite your report. See “Saving Input Control Values” on 
page 73 for more information. 

,7.1 Simple Input Controls 

The 16. Interactive Sales Report example has several input controls: 

• Product Family 

• Product Department 

• Product Category 

• Product Name 

• Country 

• Gender 

Using input controls, you mn the report with one set of data and then another. When saved, an instance of the 
report with alternate input controls is called a Report Version, and is labeled as such in the repository. 

To run a report with simple input controls: 

1. In the repository, locate and mn the report 16. Interactive Sales Report. 


TIBCO Software Inc. 


71 





TIBCO JasperReports Server User Guide 



Figure 3-10 Interactive Sales Report 

2. In the Filters panel, use the Country menu to select USA only. 


Country 

Available: 3 


Selected: 1 


Search list., 


Canada 

Mexico 


V Select All K Deselect All 


Fm Invert 


Figure 3-11 Input Control Selection - Country 

3. Click Close, then click Apply at the bottom of the panel. The report shows data for the USA only. 

151 

4. Click then select Save As. You are prompted to name the new report. 

5. Enter a new name, then click Save. 

.7.2 Multi-select Input Controls 

The 16. Interactive Sales Report has an example of a multi-select input control for Product Name. 

To run a report with a multi-select input control: 

1. In the repository, locate and mn the report 16. Interactive Sales Report. 

2. In the Filters panel, enter onion in the Search list ^ for the Product Name input control. 

Only products containing "onion" are shown. 

3. Click the first item in the list, then scroll down and Shift-click to select all the items with "onion". 

4. Click in the Search list again and delete the word onion. 
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All items are displayed, with ones that include "onion" selected. 

5. Click the Selected tab to see that only items that are selected are displayed. Then click the Available tab 
to view all the items. 

6. Click Invert to invert the selection. 

Now all items are selected except those items that contain "onion". 

7. Click Apply at the bottom of the panel. The report shows data only for products that do not contain the 
word "onion." 


Product Name 

Available: 120 Selected: 105 


Search list... 


Ebony Asparagus 


Ebony Baby Onion 



V' Select All X Mone ^ Invert 



Figure 3-12 Multi-Input Control Selection 

.7.3 Saving Input Control Values 

You can save your selected input control values to use at another time. You will have the original report and a 
copy of it JasperReports Server saves a version of the report with the selected values as a child of the original 
report. This new version of the report appears as a child of the original report in the repository, as shown in 
Figure 3-13. Click ► next to the original report in the repository to see all versions of it. 

Your saved input control values also appears in a drop-down list when you open the input controls dialog. 


Repository 
All + Reports 

o Name Description 

r 01. Geographic Results by Segment Report Sample HTML5 multi-axis column chart from Domain showing Sales, Units, and $ Per 

Geographic Results Report Filtered for Chicken Prod... 


Sort By: Name | Modified Date 


Type 

Report 

Report Version 


Created Date 
May 26 


Modified Date 
June 1 
Today 


Figure 3-13 Filtered Version of Geographic Results Report in Repository 
To save the input control values: 

1. In the repository, locate and run the report 1. Geographic Results by Segment Report. 
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2. On the tool bar, click ^ . 

3. Select all of the onion products, as described in ‘‘Multi-select Input Controls” on page 72. 

4. Click save at the bottom of the dialog box. 

5. Enter "Interactive Sales Report for Onion Products" as a name for the input control values and click Save. 
JasperReports Server saves the input control values as an option. A new drop-down box appears at the top 
of the Filters panel. 


< 


1 Options 

Interactive Sales Report for Onion Products ^ 


1 --None— 1 

Interactive Sales Report for Onion Products 



Figure 3-14 Saved Input Controls Option 

6. Select Interactive Sales Report for Onion Products from the list of options and click OK. The report shows 
data for onion-related products only. 


7.4 Cascading Input Controls 

Cascading input controls in a report reduce a large number of choices to a manageable number. A single value 
chosen for a cascading input control determines which other values appear as choices for input. For example, the 
choice of a country determines which states or regions are listed as choices. For more information, see 

“Selecting a Data Source for Running the Complex Report” on page 200. 

To run a report with cascading input controls: 

1. In the repository, locate and mn the report 16. Interactive Sales Report. 

The report mns, and appears with the Options panel open on the left side of the Report Viewer 

2. In the Options panel’s Country multi select drop-down, select a different country, for example Canada. 
The other drop-downs in the Filters panel are automatically updated with Canadian data. 


Cascading input controls are implemented as queries that access the database to retrieve the new 
values. The server displays an activity monitor while the query is running, and in the case of long 
queries, you can click Cancel and select different values. 


3. In the Product Name section, select a product to display in the report. 

4. Click Apply to mn the report with the chosen values. 


.8 Running a Report Book 

Report books are multiple reports bundled into a single object, created in Jaspersoft Studio. You can mn and 
view report books from the Fibraiy page or the repository, much like you would a standard report. However, 
report books contain some elements that are not found in standard reports. 
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To run a report book in the Report Viewer: 

1. In the repository, elick the name of the report book you want to mn. For example, elick the sample 17. 
Report Workbook. The report appears, as shown below. 


(3 17. Report Workbook Data refreshed 2019-09-23 at 13:31:53 O 
Back P, H 


— + 1100% 


TocReport 


Chart 


I search report Q, j » 


Crosstab Table 
Pa.e 290 ^ 


► 


Table of Contents 


Distribution by Countiv 4 


Customer Education 5 


Customers List 10 


1. Canada 10 

‘‘“Burnaby ... i‘o‘ 

Cliffside 12 

Haney 14 

Ladner 17 

Langford 20 

Langley 23 

Metchosin 25 

N. Vancouver 28 

Newton 30 

Oak Bay 33 

Port Hammond 36 

Richmond 38 

Royal Oak 41 

Shawnee 43 

Sooke 46 

Vancouver 49 

Victoria 51 

Westminster 54 

2. Mexico 56 

“‘Ttcapuico. 57 

Camacho 59 

Guadalajara 62 

Hidalgo 65 

La Cruz 67 

Merida 70 

Mexico City 72 

Orizaba 75 

San Andres 77 

Santa Anita 80 

Santa Fe 83 

Tixapan 84 

TIaxiaco 87 

3. USA 89 


Figure 3-15 Sample report book as seen in the Report Viewer. 


The sample report book contains three bundled reports: 

• Distribution by Country, a chart-type report. 

• Customer Education, a crosstab-type report. 

• Customers List, a table-type report. 

Each of these reports can be accessed by a tab, along with the Table of Contents page, located at the top of 
the Report Viewer. 

2. Click the Chart tab to open the Customer Distribution by Country report. Note that you can interact 
with this report as you would with a standard chart-based report in the viewer. 

3. Click the TocReport tab to return to the table of contents page. 

4. Scroll down and click the Acapulco entiy in the table of contents. The first page of the Acapulco table 
entries is displayed. 

5. Click ^ to open the bookmarks pane. 

6. Click the Customer Education entiy in the bookmarks pane. The Customer Education crosstab report 
opens in the viewer. 

7. Close the bookmarks pane by clicking the x in the upper right comer of the pane. 
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Chapter 4 Scheduling Reports and Dashboards 


Using the JasperReports Server scheduler, you can run reports and take snapshots of dashboards repeatedly and 
unattended during off hours or at other times. The reports and dashboards are saved in a file format of your 
choice to the repository, the host machine, or an FTP server. Scheduling these jobs to mn in the background or 
during off hours can reduce the performance impact on the server. 

You can view a list of scheduled reports or dashboards on the View > Schedules page. 

This chapter contains the following sections: 

• Creating a Schedule 

• Viewing the List of Scheduled Jobs 

• Changing Schedules 

• Pausing a Job 

• Deleting a Job 

• Running a Job in the Background 

• Event Messages 


4.1 Overview of the Scheduler 

Using the scheduler, you set up a schedule for generating reports or dashboard with parameters, output options, 
and notifications: 

• Schedule - When to mn the scheduled job, and how often 

• Parameters - If the report or dashboard was designed with input controls, which parameters the scheduled 
job will use 

• Output Options - The name of the output file, the output format and locale, and where the output file is 
stored 

• Notifications - Email options for sending the output to recipients and for sending administrative messages 

The permissions of the user who schedules a job determines the data that is exposed. For example, Gloria only 
has access to inventory data from the Southeast US region. A report that she schedules only shows data from 
that region, even when the report is viewed by users in other regions. Other users schedule the report themselves 
to see the data for their own regions. 



Sensitive data could be exposed to unauthorized users if you schedule a job as an administrative user 
with no data restrictions because the output will contain all requested data in the data source. Any user 
who receives the output can view all the data regardless of the user’s access restrictions. 
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Scheduling a dashboard requires having Chrome/Chromium installed on the computer hosting JasperReports 
Server. For information on configuring Chrome/Chromium for dashboards, see the System Configuration 
chapter in the TIBCO JasperReports Server Administrator Guide. 


.2 Creating a Schedule 

To create a schedule: 

1. Locate the report or dashboard you want to schedule in the repositoiy. 

2. Right-click the report or dashboard and select Schedule... from the context menu, or if it already has a 
schedule, click the schedule icon . The Scheduled Jobs page appears. 

Scheduled Jobs 

/public/Samples/Reports/04,_Product_Results_by_Store_Type_Report 
Back Create Schedule Run Now Refresh List 

Job ID Job Name Owner State Last Run Next Run Enabled 

Figure 4-1 Scheduled Jobs Page 

3. Click Create Schedule. The Schedule tab of the scheduler appears. 


New Schedule 


Schedule For: /public/Samples/Reports/04._Product_Results_by_Store_Type_... 


Schedule 


Parameters 


Output Options 


Notifications 


Schedule Start 

Start Date: 

# Immediately 
O On Specific Date: 

I 


Time Zone: 

I America/LQS_Angeles - Pacific Standard Time ^ | 


Recurrence 

Recurrence Type: 

I None ^ 


Figure 4-2 New Schedule Tab 

4. Set a start date, choosing whether to mn immediately or on a specific date. If a specific date is selected, 
click the calendar icon ^ to select a start date and time. 

5. Specify the time zone for the schedule. The default time zone is the time zone of the server, the time zone 
you entered at log in. If you’re in a different time zone, set this field accordingly. 

6. Choose a recurrence setting, as described in ^‘Running a Job Repeatedly” on page 84. If you select Simple 
or Calendar Recurrence, additional controls appear on the page. 

• None: Run the job once. 
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• Simple: Schedule the job to recur at a regular interval, specified in minutes, hours, days, or weeks. 

• Calendar: Schedule the job to recur on days of the week, days of the month, specific dates, or date 
ranges. 



If you set up a job with simple recurrence to start immediately, the job schedule will change after 
export/import or a server restart. This happens because the job does not retain the previous run 
history and therefore starts immediately after import or restart. If you have a large number of 
scheduled jobs, all scheduled jobs with simple recurrence will attempt to start at the same time after 
export/import or restart. This can impact server performance. In addition, some scheduled jobs may 
be locked out and they will continue to try to run. 

To ensure a recurring schedule does not change after export/import or restart, either use simple 
recurrence with a specific start time, or set up calendar recurrence. 


7. If the report or dashboard you are scheduling has input controls that prompt for user input, click the 
Parameters tab. 


New Schedule 

Schedule For: /public/Samples/Reports/04._Product_Results_by_Store_Type_. .. 


Schedule 


Parameters 


Output Options 


Notifications 


Save Current Values 


Country 
Canada 
Search list... 

Canada 
Mexico 
No Country 
USA 


Figure 4-3 Set the Parameter Values Page for Scheduling a Report 

Saved values, if there are any, appear in a drop-down list at the top of the page, as shown in Figure 4-3. In 
the Use saved values drop-down, you can set the input controls defined for the report or dashboard you’re 
scheduling. You can set the input values for the scheduled job, and click Save Current Values to save the 
input value as a named set of values. 

For more information about using saved values and saving input values, see ‘‘Running a Report with Input 
Controls or Filters” on page 71. 

8. Choose a set of saved values, or set the input controls. 

9. Click the Output Options tab and set the output format and location, as described in Setting Output 
Options. 

10. Click the Notifications tab and set up email notifications, as described in Setting Up Notifications 

11. Click Save. The Save dialog box appears. 

12. In the Scheduled Job Name field, enter a name for the job, for example. Weekly Report. The description 
is optional. 
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13. Click Save to save the schedule. The job appears in the list of saved jobs for the report or dashboard. 


.2.1 Setting Output Options 

On the Output Options tab, you can change these settings: 

• File name - The base name for the output file in the repository. This name must be unique; if you attempt 
to create a schedule with the same file name as an existing output file, you will not be able to save. 

• Description - The optional description of the file that appears to users who view the repository. 

• Time Zone- The output time zone for generating the report. 

• Output Locale - The locale settings for generating the report. 

The report must support locales, for example a report based on a Domain with locale bundles. For more 
information on locale bundles, see TIBCO JasperReports Server Data Management Using Domains. 

• Formats - The available output formats. Select one or more formats; the default format is PDF. When you 
select more than one, each format is stored as a separate file in the selected output destination. 

• Canvas Size - Sets the size of the canvas when exporting a dashboard. 

• File Handling - Select one or more checkboxes to specify handling for multiple output files with the same 
name: 

• Overwrite Files - Overwrites old output files with newer ones of the same name. 

• Sequential File Names by Timestamp - Appends a timestamp to the names of files created by the 
job. Useful for the output of recurring jobs or for time-sensitive reports where the output must be dated. 
When the timestamp is used, the output filename is <basename>-<timestamp>. <extension>. Note 
that, depending on the frequency of the schedule and the format of the timestamp, it may be possible to 
have two output files with the same name; in this case, modify the timestamp or use the Overwrite 
Files checkbox to specify the behavior you want. 

• Timestamp Pattern - When Sequential File Names by Timestamp is selected, a required pattern 
for the timestamp, based on the java. text. SimpleDateFormat is required. Valid patterns for output 
files can contain only letters, numbers, dashes, underscores, and periods. The default pattern is 

yyyyMMddHHmm, for example 200906150601. 

• For more information about the valid patterns for this field, refer to: 
http://download.oracle.eom/javase/6/docs/api/java/text/SimpleDateFormat.html 
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New Schedule 

Schedule For: /public/Samples/Reports/04._Product_Results_by_Store_Type_... 


Schedule 


Parameters 


Output Options 


Notifications 


Output File Options 

File name (required): 

^4.Product Results by Store Type RepQrt 

Description: 


Time Zone: 


I America/Los Angeles ■ 

• Pacific Standard Time | 


Output Locale: 

I (Default) 

V I 


Formats: 

□ CSV 

□ HTML 

□ RTF 

□ DOCX 

□ ODS 

□ XLSX 

□ Excel (Paginated) 

□ ODT 

□ XLSX (Paginated) 

□ Excel 

Q PDF 

□ PPTX 


File Handling: 

Q Overwrite Files 

□ Sequential File Names by Timestamp 


Timestamp Pattern; 



Cancel 


Figure 4-4 Output Page for Scheduling a Report - Output File Options 

• Output Destination - To save the output file, select one or more checkboxes to specify the output 
location. If you do not want to save the report output (for example, if you only want to email the report) 
leave all checkboxes blank. 

• Output To Repository - If checked, saves the report output to the specified location in the repository. 
You must have write permission to the output folder. JasperReports Server validates the path when you 
click Save and will display an error message if the location doesn't exist. You can change the 
repository location that appears here by default. See TIBCO JasperReports Server Administrator Guide 
for more information. 

• Output To Host File System - If checked, saves the report output to the specified folder on the 
Server host machine; check with your administrator for the correct location to enter. Output To Host 
File System must be configured by an administrator; if the check box is grayed out, saving to the host 
file system has not been enabled for your system. See the TIBCO JasperReports Server Administrator 
Guide for more information 

• Output To FTP Server - If checked, saves the report output to the specified FTP server. You must 
have write permission to the selected directory on the FTP server. Enter the following properties of your 
FTP server: 

• Server Address - The host, IP address or URL of the FTP server. 

• Port - Specifies the FTP connection port. For FTP, the default port is 21; for FTPS, the default port 
is 990; for SFTP, the default port is 22. 

• Transfer Protocol - Specifies the file transfer protocol that the server uses. You can select one of 
the following: 

• FTP. 
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• FTPS (FTP over SSL). 

• SFTP (FTP over SSH). If selected, the SSH Key Authentication checkbox and SSH private 
key fields appear. 

• SSH Key Authentication. Check if the server requires an SSH private key for SFTP transfers. 

• Path to SSH Private Key. When SSH Key Authentication is checked, the location of the SSH 

private key in the repository is required. 

• SSH Key Passphrase. When SSH Key Authentication is checked, enter the passphrase for the 
SSH private key, if it has one. 

• Directory - The directory on the FTP server where the report output is saved. 

• Username - The username for access to the FTP server. 

• Password - The password for the username. 


New Schedule 

Schedule For: /public/Sannples/Reports/04._Product_Results_by_Store_Type_... 


Schedule 


Parameters 


Output Options 


Notifications 


Output Destination 

Q Output To Repository 


/public/Samples/Reports Browse... 


Output To Host File System 


Q Output To FTP Server 
Server Address: 


Port: Transfer Protocol: 

[22 I I SFTP (FTP over SSH) 

Directory: 


Username: Password: 


Test Connection 


Save 


Cancel 


] □ SSH Key Authentication 

Path to SSH Private Key: 

] Hlnt;/sshKeys/myopenssHKey 

SSH Key Passphrase (optional): 


Figure 4-5 Output Page for Scheduling a Report - Output Destination 

When you click Save, the job appears in the list of scheduled jobs. 


.2.2 Setting Up Notifications 

On the Notifications page, you can set up email notifications to the recipients of the report or dashboard and to 
administrators. 


Notifications are sent to all users with the organization ROLE_ADMINISTRATOR role, who belong to the 
same organization as the user who creates the scheduled job. 
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Send report when scheduler runs: 

Enter one or more email addresses to send the output after the job has mn. You can configure the following: 
• To - One or more email addresses separated by commas for sending email notification. 



By default, the mail server is not configured by the JasperReports Server installer. To send email 
notifications, the administrator must configure the mail server, as described in the TIBCO 
JasperReports Server Installation Guide. 


• CC - One or more email addresses separated by commas for sending an email notification on the CC line. 

• BCC - One or more email addresses separated by commas for sending blind carbon-copy email 

notification; the addresses in this field are not revealed to the other recipients. 

• Subject - The subject line of the notification email. 

• Message - Content of the notification email. 

• Choose one of the radio buttons to specify how email recipients access the output: 

• Include reports/dashboards as repository links in email body - Sends a link to the output in the 
repositoiy. Not available unless Output to Repository is selected on the Output Options tab. 

• Include report/dashboard files as attachments - Sends the output as attachments to the 
notification email. If you have selected multiple output formats, each one is attached as a separate file 
to the email notification. 

• Include report/dashboard files as ZIP attachment - Zips all outputs into a single archive file 
before attaching to the email. 

• Include HTML report in email body - Displays the report directly in the email body. This option is 
available only when Include report files as attachments or Include report files as ZIP 
attachment is checked and HTML is selected as one of the options on the Output File Options page. 
When this option is selected, you cannot include a message in the email body. This option is not 
available for dashboards. 



Be careful when sending reports containing sensitive data by email, either in the email body or as an 
attachment. 


• Do not send emails for empty reports - A check box option that, if checked, prevents the server from 
attaching empty report output files to email notifications. This applies to parametrized reports where there is 
no data that matches the parameters. This option is not available for dashboards. 


Send Job status notifications: 

Enter one or more email addresses to send notification of job success or failure to administrators: 
• To - One or more email addresses separated by commas for sending email notification. 



By default, the mail server is not configured by the JasperReports Server installer. To send email 
notifications, the administrator must configure the mail server, as described in the TIBCO 
JasperReports Server Installation Guide. 


• Subject - The subject line of the notification email. 

• Send success notification - Check box option that, when checked, sends a notification when the 
scheduled job mns. 

• Success Message - The message in the body of the notification email sent on success. 
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• Send failure notification - Check box option that, when checked, sends a notification when the 
scheduled job fails to run. 

• Failure Message - The message in the body of the notification email sent on failure. 

• Include report/dashboard job information - A check box option that, if selected, includes the report or 
dashboard's label, ID, description, and job status in the notification email. 

• Include stack trace - A check box option that, if selected, includes the stack trace for failed jobs in the 
body of the email. 


New Schedule 

Schedule For: /public/Samples/Reports/04._Product_Results_by_Store_Type_... 


Schedule 


Parameters 


Output Options 


Notifications 


Email Notification 

Send report when scheduler runs 
To: 


Send job status notifications 
To: 


use commas to addresses 


use comrr rs to separate addresses 


CC: 


BCC: 


Subjert: 


Message: 


# Include reports as repository links in email body 
O Include report files as attachments 
O Include report files as ZIP attachment 
Include HTML report in email body 
□ Do not send emails for empty reports 


Subject: 


□ Send success notification 
Success Message: 


O Send failure notification 
Failure Message: 


□ Include report job information 

□ Include stack trace 


Save 


Cancel 


Figure 4-6 Notifications Page for Scheduling a Report 

.2.3 Running a Job Repeatedly 

To mn jobs automatically on a regular basis, select simple or calendar recurrence on the Schedule tab: 

• Simple recurrence repeatedly mns the job at a regular interval set in minutes, hours, days, or weeks. 

• Calendar recurrence involves more settings: time of day, days of the week, or days of the month, and 
months of the year. 

In Figure 4-7 you can see an example of how to set simple recurrence. 
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New Schedule 


Schedule For: /public/Samples/Reports/04._Product_Results_by_Store_Type_... 


Schedule 


Parameters 


Output Options 


Notifications 


Schedule Start 

Start Date: 

O Immediately 
# On Specific Date; 

[2020-08-26 00:00 \ M 

Time Zone: 

I America/LQS_Angeles - Pacific Standard Time ^ 


Recurrence 


Recurrence Type: 

I Simple ^ I 

Repeat every (required): 

|l I I days 


Schedule End 
End Date: 

O Run a set number of times 
Number of runs; 


O Run until a specified date; 

I I n 

# Run indefinitely 


Holidays 

Calendar of dates to exclude: 
[None 


Figure 4-7 Simple Recurrence Settings 

Simple recurrence options are: 

• Repeat every - The interval between jobs, in minutes, hours, days, or weeks. 

• Run a set number of times - Runs the specified number of times. 

• Run until a specified date - Runs until a calendar date is reached. Click the calendar icon, ^ , to 

select the date. 

• Run indefinitely - Runs at the specified times until you delete the job. 

• Holidays - A holiday calendar specifies a list of days when the scheduled job will not mn. To use a 

holiday calendar, select it from the drop-down list. Only one holiday calendar can be selected at a time. 

Holiday calendars are configured by an administrator; if no calendars are available in this list, this 

option has not been configured for your system. 


If your server recognizes Daylight Savings Time (DST), jobs scheduled using simple recurrence may 
seem to occur one hour later (when DST ends) or one hour earlier (when DST begins). If you want 
jobs to recur at the same time of day and respect DST adjustments, use calendar recurrence. 
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If you set up a job with simple recurrence to start immediately, the job schedule will change after 
export/import. This happens because the imported job does not retain the previous run history and 
therefore starts immediately after successful import. To ensure a recurring schedule does not change 
after export/import, either use simple recurrence with a specific start time, or set up calendar 
recurrence. 


In Figure 4-8 you'll see an example of calendar recurrence settings. 


New Schedule 

Schedule For: /public/Samples/Reports/04._Product_Results_by_Store_Type_.. 


Parameters Output Options 


# On Specific Date: 


2020 - 08-26 00:00 


HI 


Time Zone: 

I America/Los Angeles - Pacific Standard Time 


Recurrence 


Recurrence Type: 


1 Calendar 

-1 


Months: 

Days: 

Times: 

# Every Month 

O Every Day 

Hours (required): 

O Seleaed Months: 

# Seleaed Days: 

[20 J 


Jan 


Sun 

Enter'-" r: like 9,12,15 or ranges 


Feb 


Mon 

like 9-12,1-17 


Mar 


Tue 



Apr 


Wed 

Minutes (required): 


May 


Thu 

L° J 


Jun 


Fri 


Jul 


Sal 

Enter 0,15,30,45 to run every 1/4 hour 


Aug 

Sep 

O Dates in Month: 



Oct 

L J 



Nov 


Enter dates (9,12,15) or date ranges (9- 



Dec 


12,1-17) 



Schedule End 
End Date: 

I \m 


Holidays 

Calendar of dates to exclude: 
I None 


Figure 4-8 Calendar Recurrence Settings 

Calendar recurrence options are: 

• Months - The months during which the job mns. 

• Every Month 

• Selected Months 
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• Days - The days when the job runs. 

• Every Day 

• Selected Days 

• Dates in Months - Enter dates or date ranges separated by commas, for example: 1, 15. 

• Times - The time of day in minutes and hours when the job should mn. The hours use 24-hour format. 
You can also enter multiple minutes or hours, and ranges, separated by commas. For example, entering 
0,15,30,45 for the minutes, and 9-17 for the hours, mns the report eveiy 15 minutes from 9:00 a.m. to 
5:45 p.m. Enter an asterisk to mn the job every minute or every hour. 

• End Date - Calendar recurrence mns until a calendar date is reached. Click ^ to select the date. 

• Holidays - A holiday calendar specifies a list of days when the scheduled report will not mn. To use a 

holiday calendar, select it from the drop-down list. Only one holiday calendar can be selected at a time. 
Holiday calendars are configured by an administrator; if no calendars are available in this list, this option 
has not been configured for your system. 

Administrators see the chapter on scheduling in the TIBCO JasperReports Server REST API Reference for 
more information on configuring calendars. 


.3 Viewing the List of Scheduled Jobs 

View a list of all scheduled jobs: 

All scheduled jobs that the user has defined appear on the Click View > Schedules page. 
Schedules 




Resource 

Job Name 

Job ID 

Owner 

Last Run 

Next Run 

Enabled 

OL Geographic Results by Segment R... 

/public/Samples/Reports/Ol._Geogra... 

01 Geographic Results... 

2309 

superuser 

2020-07-221... 

2020-07-291... 

Q 

01. Geographic Results by Segment R... 

/p u blic/Sam ples/Reports/0l._Geogra... 

01 Geographic Results... 

2301 

superuser 

2020-07-221... 

2020-07-231... 

□ 


Figure 4-9 The Schedules Page 

Typical users see only the jobs they have defined; administrators see the jobs defined by all users. In Figure 4- 
9, jasperadmin has scheduled two jobs for the Geographic Results by Segment report. 

You can use the Schedules page's search field to find the scheduled job you want. 

The Schedules page shows the name of the scheduled report or dashboard, the repositoiy URI of the job, the 
internal ID number of the job, the user (owner) who created the job, and the state of the job. Job states are: 

• NORMAL - The job scheduled. 

• EXECUTING - The erver is generating the output. 

• COMPLETE - The erver has finished mnning the job and placed output to the repository. 

• PAUSED- The job has been disabled. Click Enabled to resume the schedule. 

• ERROR - The scheduler encountered an error while scheduling or triggering the job. This doesn’t include 
cases where the job is successfully triggered, but an error occurs while it mns. 

• UNKNOWN - The scheduler encountered an error with the job trigger. 

The Schedules page includes these controls: 
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• Enabled checkbox - When checked, the job will run at the scheduled times. When unchecked, the job is 
paused. 

• ^ - Edits the schedule. 

• nD- Deletes the scheduled job. 

When the server receives a request to delete a job that is mnning, the server completes mnning the job 
before deleting it. 

View scheduled jobs for an individual report or dashboard: 

Scheduled jobs appear in the repository with a ^ icon beside the report or dashboard's name. To view the list 

of scheduled jobs for a report or dashboard, locate it in the repository, click on the icon or right-click the 
report or dashboard, and select Schedule from the context menu. The Scheduled Jobs page appears. The 
Scheduled Jobs display information that's similar to the Schedules page. 


You can filter search results for scheduled jobs in the repository using the following options: Any 
schedule (scheduled and unscheduled reports), Scheduled, Scheduled by me, or Not scheduled. See 
1.5.2, “Filtering Search Resuits,” on page 17 for more information. 


Buttons on the Scheduled Jobs page include: 


Button 

Description 

Back 

Returns to the repository. 

Create Schedule 

Opens the Schedule tab to define a new job. 

Run Now 

Opens the scheduler and allows you to run the job immediately. See “Running a Job in 
the Background” on page 89. 

Refresh List 

Refreshes the list of jobs, for example to see if a job has finished running. 


.4 Changing Schedules 

If the start date for a schedule has not yet passed, you can edit the schedule. Once the start date for a schedule 
has passed, create a new schedule rather than changing the start date. 

To edit a schedule: 

1. Click View > Schedules. 

2. Click ^ in the row of the job you want to change. 

3. Make the changes on the Schedule, Parameters, Output, and Notifications pages. 

4. Click Save. The update occurs immediately. 
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5 Pausing a Job 

To stop a job from mnning without deleting it, disable the job. 

To pause a scheduled job: 

1. Click View > Schedules. 

2. In the row of the job you want to stop, uncheck Enabled. 

To resume a paused job: 

1. Click View > Schedules. 

2. In the row of the job you want to resume, check Enabled. When a stopped job is re-enabled, it waits until 
the next scheduled time to mn. 

6 Deleting a Job 

To delete a scheduled job: 

1. Click View > Schedules. 

2. In the row of the job you want to delete, cliek DD. 

7 Running a Job in the Background 

Running a job in the background generates a report or exports a dashboard without intermpting your workflow. 
You can keep working in the server as the job mns. When the job completes, you can export the job directly to 
any format and save it in the repository. You can the share the output with others by sending it by email. 

Running a job in the background is equivalent to scheduling it to mn immediately without recurrence. 

To run a job in the background: 

1. Locate the report or dashboard you want in the repository. 

2. Right-click the report or dashboard and select Run in Background from the context menu. 

3. Set the output format and location, as described in Setting Output Options. By default, the output is saved 
in the repository. 

4. If the job you are mnning has input controls that prompt for user input, click the Parameters tab. Choose a 
set of saved values, or set the fields one at a time. 

5. Click the Notifications tab and set up email notifications, as described in Setting Up Notifications 

6. Click Save. The job begins to mn immediately. 

8 Event Messages 

When an event occurs (for example, a scheduled report returns errors), JasperReports Server sends the owner of 
the job a notification message. You can browse these messages to troubleshoot report scheduling problems in 
the server. For example, you can determine that a job fails because its data source configuration uses incorrect 
credentials. 
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A common cause of the error message indicating that the job failed to execute is an incorrectly configured 
mail server. The mail server must be manually configured after installation in order for users to send email 
notifications. 


The Messages page displays the list of events logged for the current user. 

To open the Messages page: 

1. On any page, click View > Messages. The Messages page appears. 

2. To view a message, click its name. The message opens in the Message Detail page. 

3. To activate the buttons on the Messages page, click in a blank area of the message row that you want to 
manage. The buttons become enabled. 


Messages: All 

Mark as Read 

Subject 

Maik as Uniead 

Delete 

Date 

Type 

Component 



The job failed to execute. Review its parameters Today Error Report Scheduler 


Figure 4-10 Message Management Buttons 

4. Use the buttons on the Messages page to manage the list of messages. 
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This section describes functionality that can be restricted by the software license for JasperReports Server. 
If you don’t see some of the options described in this section, your license may prohibit you from using 
them. To find out what you're licensed to use, or to upgrade your license, contact Jaspersoft. 


The Ad Hoc Editor is the interactive designer for creating and editing an Ad Hoc view, where you can explore 
and analyze data from your Topic, Domain, or OLAP data source. Ad Hoc views can also be used to create 
content for reports. 

This chapter discusses the Ad Hoc Editor and Ad Hoc views, and includes the following sections: 

• Overview of the Ad Hoc Editor 

• Working with Tables 

• Working with Charts 

• Working with Standard Crosstabs 

• Working with OLAP Connection-based Crosstabs 

• Calculated Fields and Measures 

• Using Filters and Input Controls 

• Creating a View from a Domain 

• Working with Topics 

After you create an Ad Hoc view, you - and other users with the proper permissions - can mn the report, then 
further refine the displayed information and personalize the look of the report in the report viewer. For more 
information on that process, see ^‘Running Reports and the Report Viewer” on page 55. 


5.1 Overview of the Ad Hoc Editor 

The Ad Hoc Editor is an interactive tool for creating views for various types of reports: tables, crosstabs, and 
charts. You create these views by simply dragging and dropping elements. You can add and summarize fields, 
define groups, label and title the report, and format data for each field. The effects of your changes are evident 
immediately, and you can adjust the display to highlight the most relevant and compelling aspects of your data, 

The Ad Hoc Editor provides analysis options (such as slice, pivot, and filter) to help you recognize trends and 
outliers in your data. You can drill into specific details or analyze your data at a very high level. 

To open the Ad Hoc Editor: 

1. Click Create > Ad Hoc View. This opens the Select Data dialog. 
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2. Choose your data source from the list and click OK. 


Select Data 


[m] 


o 

o 

[ni] 

[m] 

[ml 

Eul 

[m] 


AH Accounts Report 
Audit Arc hive Domain 
Audit Domain 

Cascading multi select topic 

Customers Report 

demo for ad hoc 

Diagnostic Topic 

Employees 

ExampleVDSDomain 

Foodmart 

Foodmart 

Foodmart 




Cancel 


Figure 5-1 List of Data Sources in the Select Data Dialog 

The Ad Hoc Editor contains the following panels, from left to right: 

• Data Source Selection, which contains the fields, dimensions, and measures available in the source 
Domain, Topic, or OLAP connection. 

• Ad Hoc View, the main view design panel. 

• Filters, which defines a subset of data to retrieve from the data source. 
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OR 
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WA 
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► B Opportunities 
123 Spacer 


• Custom Filter Expression 


Figure 5-2 User Interface of the Ad Hoc Editor 

We’ll discuss how to use these panels to create an Ad Hoc view later in this section. 


.1.1 Ad Hoc Sources: Topics, Domains, and OLAP Connections 

The following repository objects provide a prepared connection to a data source for Ad Hoc view creation: 

• Topics, JRMXL files created externally and uploaded to JasperReports Server as a basis for Ad Hoc views. 

• Domains, virtual views of a data source that present the data in business terms, allow for localization, and 
provide data-level security. 

• OLAP Connections, multi-dimensional views of data that allow users to analyze a large number of 
aggregate data levels. 

You can also open and edit an existing Ad Hoc view to create a new Ad Hoc view. 

5.1.1.1 Topics 

Generally, an administrator or Jaspersoft Studio user creates a Topic as a JRXML file. The JRXML topic is then 
associated with a data source in the server. A Topic can also be created from a Domain in the server. Both types 
of topics appear in the Select Data wizard when you create an Ad Hoc view. 

Using a Topic as your source generates an empty view, which allows you to begin adding data to your view 
right away, without choosing, pre-filtering, or changing display names of the data (all of which are required 
steps when creating a Domain-based view). 

The views in the /Ad Hoc Components/Topics folder populate the Topics tab that appears when users click 

Create > Ad Hoc View. 
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To begin designing a Topic-based view: 

1. Launch the Ad Hoc Editor by clicking Create > Ad Hoc View. 

2. In the Select Data wizard, click ^ and navigate to Ad Hoc Components > Topics. 

3. Expand the Topics folder and select a topic. 

4. Select the type of view you intend to create: table, chart, or crosstab. For an overview of view types, see 

‘‘Ad Hoc View Types” on page 95. 

You can now begin working on your view in the Ad Hoc Editor. 

5.1.1.2 Domains 

Administrators create Domains that typically filter the data, create input controls, and manage the list of 
available fields and measures. A Domain specifies tables in the database, join clauses, calculated fields, display 
names, and default properties, all of which define items and sets of items for creating Ad Hoc views. 

Unlike Topics, which must be stored in a specific folder in the repositoiy. Domains are detected regardless of 
their location in the repository. The /Domains folder is included for your convenience, but the Domains tab in 
the Source dialog displays all the Domains to which you have access in the repository. 

To begin designing a Domain-based view: 

1. Launch the Ad Hoc Editor by clicking Create > Ad Hoc View. 

2. In the Select Data wizard, click ^ and navigate to Domains. 

3. Expand the Domains folder and select a domain. 

4. Click Choose Data..., and click the options on the left of the window to perform the following tasks: 

• Click Fields to select fields of data to use in the view. 

• Click Pre-filters to create filters to limit the data available in the Ad Hoc Editor. 

• Click Display to change the fields’ display names. 

• Click Save as Topic to save the customized topic for later use. 

5. Select the type of view you want to create: table, chart, or crosstab. For an overview of view types, see “Ad 

Hoc View Types” on page 95. 

You can now begin working on your view in the Ad Hoc Editor. 

5.1.1.3 OI_AP Connections 

Administrators create OLAP client connections that expose transactional data and define how the data can be 
seen as a multidimensional cube. An OLAP connection can expose multiple cubes in a single OLAP 
connection. 



With OLAP connections, you can create chart and crosstab views only. 


To begin designing an OLAP connection-based view: 

1. Launch the Ad Hoc Editor by clicking Create > Ad Hoc View. 

2. In the Select Data wizard, click ^ and navigate to Analysis Components > Analysis Connections 
and select a sample project and a connection. 

You can now begin working on your view in the Ad Hoc Editor. 

For more information about OLAP-based view functionality, refer to the following sections: 
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• ^‘Working with OLAP Connection-based Crosstabs” on page 132 

• ^‘Working with Topics” on page 169 


5.1.2 Ad Hoc View Types 

The Ad Hoc Editor allows you to select from three view types: 

• Tables, which are used to view values in the database and to summarize the values in columns. 

• Charts, which compare one or more measures across multiple sets of related fields. 

• Crosstabs, which aggregate data across multiple dimensions. 

This section provides an overview of each view type. The design and content tasks for working with each type 
of view are discussed in more detail in the following sections: 

• For more information on table views, see ^‘Working with Tables” on page 109. 

• For more information on chart views, see “Working with Charts” on page 115. 

• For more information on crosstab views, see “Working with Standard Crosstabs” on page 127. 

5.1.2.1 Tables 

The architecture of a table view consists of columns, rows, and groups. 

Columns in a table correspond to the columns in the data source. They are included by adding fields or 
measures to the table in the Ad Hoc view. 

Rows correspond to rows in the database. The information in each row depends on what columns are included 
in the table. 

Using groups, rows can be grouped by identical values in any field with intermediate summaries for each 
grouped value. For example, a table view of product orders might contain columns to show the dates and 
amounts of each order, and its rows might be grouped by city and product. 
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Date Placed 

Date Filled 

Payment Received 

City A 

Product 01 


Date 

Date 

Amount 


Date 

Date 

Amount 

Product 01 totals: 


Count 

Sum 
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Date 

Date 

Amount 


Date 

Date 

Amount 

Product 02 totals: 


Count 

Sum 

Product 03 
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Date 

Amount 


Date 

Date 

Amount 

Product 03 totals: 


Count 

Sum 

City A totals: 


Count 

Sum 

City B 

Product 01 


Date 

Date 

Amount 


Date 

Date 

Amount 


Date 

Date 

Amount 






For more information on working with tables, see “Working with Tables” on page 109. 

5.1.2.2 Charts 

Charts summarize data graphically. Types of charts include bar chart, line chart, and pie chart, among others. 
With the exception of time series and scatter charts, each type of chart compares summarized values for a group. 
For example, the Chart tab might show the data in a bar chart that compared the sum of Payments Received for 
each of the products in each of the cities. 
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Total Payments Received 



City A 

City B 

City C 

Product 01 

■ Product 02 ■ Product 03 


Time series and scatter charts use time intervals to group data. 

For more information on working with charts, see ‘‘Working with Charts” on page 115. 

5.1.2.3 Crosstabs 

Crosstabs are more compact representations than tables; they show only aggregate values, rather than individual 
database values. Columns and rows specify the dimensions for grouping; cells contain the summarized 
measurements. For instance, the example above could be displayed in a crosstab with columns grouped by sales 
manager and year. 
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For more information on working with crosstabs, see “Working with Standard Crosstabs” on page 127. 

OLAP connection-based crosstabs behave differently than those created from Topics or Domains. See “Working 
with Topics” on page 169. 


5.1.3 The Data Source Selection Panel 

The Data Source Selection panel contains a list of available fields in the chosen Topic or Domain. If you are 
using a Domain, fields may appear in nested sets. Use the arrow beside the set name to expand or collapse a set 
of fields. 

Available fields may be divided into two sections in the panel. Fields and Measures. You can use the search 
field in each section to locate a specific field or measure. 

To hide this panel, click < in the top left comer; this is helpful when arranging content in a large Ad Hoc view. 
Click the same icon on the minimized panel to expand it. 

For more information on working with fields, see “Using Fields in Tables ” on page 110, “Using Fields and 
Measures in Charts” on page 116, and “Using Fields in Crosstabs” on page 128. 


5.1.4 The Ad Hoc View Panel 

The Ad Hoc View panel provides tools that allow you to control what data is included in a view, and how it is 
organized. 

Along the top of the panel, there is a tool bar and a drop-down menu. 

The drop-down menu contains options for displaying a subset of the available data (Sample Data), all 
available data (Full Data), or none of the available data (No Data) in the view. Using the sample data can 
make the design process quicker by loading less data. Use the subset for initial design; use the frill set for 
refining layout elements such as column width. This drop-down menu is not available for charts, which use all 
available data. 
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By default, the editor displays only a smaller, sample set of the data in the table. Use the drop-down menu to 
select Full Data to view the full set of data. 



Depending on its configuration, JasperReports Server may load a Topic, Domain, or OLAP connection’s 
entire result set into memory when you edit the view, or run a report from it. If the data policies and other 
options that control JasperReports Server’s memory are disabled, ensure that each Topic, Domain, or 
OLAP connection returns a manageable amount of data, given the environments load capacity. 
Alternately, you can change the server’s configuration. 


The tool bar at the top of the panel provides access to many functions of the Ad Hoc Editor. The toolbar is 
described in Table 5-1 on page 99. 


Table 5-1 Ad Hoc Editor Tool Bar Icons 


Icon 

Name 

Description 

o 

Display 

Mode 

Click this icon to hide the editor interface. This mode provides a subset of the 
editor’s full feature set. 

ISI 

Save 

Place the cursor over this icon to open a menu of save options. 

(H 

Export 

Place the cursor over this icon to open a menu of export options. 


Undo 

Click this icon to undo the most recent action. 


Redo 

Click this icon to redo the most recently undone action. 

n 

Undo All 

Click this icon to revert the view to its state when you last saved. 

Q 

Switch Group 

Click this icon to change the way groups are displayed. For more information, refer 

to “Creating a View from a Domain” on page 164. 

u 

Sort 

When working with tables, click this icon to view the current sorting and to select 
fields for sorting data. For more information, refer to “Sorting Tabies” on page 113 

m 

Input 

Controls 

Click this icon to see the input controls applied to this view. For more information, 
refer to “Using input Controis” on page 161. 


Page Options 

Place the cursor over this icon to open a menu of page-level options. You can: 

• Change whether to display the Layout Band. 

• Change whether to display the title area. 

• In crosstabs, you can merge or unmerge cells with the same data. 


View 

SQL/M DX 
Query 

For more information on viewing SQL queries, see “Viewing the SQL Query” on 
page 100 

For more information viewing MDX queries, see “Viewing the MDX Query” on 
page 135 


TIBCO Software Inc. 


99 


















TIBCO JasperReports Server User Guide 


Icon 

Name 

Description 

ii. 

Select Visu¬ 
alization 

Type 

Click this icon to select the type of table, chart, or crosstab you want to use in your 

Ad Hoc view. For information on all the types of visualizations available, see “iThe 
Visuaiization Seiector” on page 100 for more information. 


5.1.4.1 The Layout Band 

Directly beneath the tool bar is the Layout Band. Here there are two fields. These fields have different labels 
and fianctions, depending on the type of view you are creating: 

• For tables, these fields are Columns and Groups. 

• For charts, these fields are Columns and Rows. 

• For crosstabs, these fields are Columns and Rows. 

You can drag and drop fields and measures into these boxes to populate your view. 

5.1.4.2 Managing Canvas Options 

When working with a table or chart view, the Canvas Options selector appears below the Layout Band, to the 
left of the view title. This tool allows you to control the level of detail displayed in your table or chart. Click 

to display the options available for your Ad Hoc view type. 

For tables, the Canvas Options selector includes the following options: 

• Detailed Data (default) displays table detail only. 

• Totals Data displays table totals only. 

• Details and Totals displays both details and totals. 

• Show/Hide Duplicate Rows, which displays only the distinct values in your table if you choose to hide 
the duplicate rows. 

For charts, the Canvas Options selector includes the following options: 

• Chart Format displays formatting options. 

5.1.4.3 Viewing the SQL Query 

You may want to look at the SQL query for your view, to verify what data users are hitting. If you have the 
proper permissions, you can do this in the Ad Hoc Editor with the View Query button. 

The query is read-only, but can be copied onto a clipboard or other document for review. 

To view the SQL query: 

• In the tool bar, click . 

The View Query window opens, displaying the SQL query. 


5.1.5 IThe Visualization Selector 

The Visualization Selector lets you switch between Ad Hoc view types, allowing you to choose the best way to 
represent your information in the Ad Hoc view, including: 

• Table, which displays values corresponding to the rows and columns in the data source. 

• Crosstab, which compares one or more values across multiple sets of related fields. 

• Column, which compares values displayed as columns. 
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• Bar, which compares values displayed as bars. 

• Line, which compares values displayed as points connected by lines. 

• Area, which compares values displayed as shaded areas. 

• Spider, which compares three or more values on a series of spokes. Spider charts can use columns, lines, or 
areas to display values. 

• Dual- and Multi-Axis, which display values using two or more measures. 

• Time Series, which compares time intervals displayed as points connected by lines. The Time Series chart 
type is only available for non-OLAP charts. 

• Scatter, which compares values as individual points arrayed across both axes of a chart. 

• Bubble, which compares three measures displayed as circles of varying sizes arrayed across both axes of a 

chart. 

• Pie, which compares values displayed as slices of a circular graph. 

• Range, which displays values as heat and tree maps. Only the Heat Map chart is available for OLAP data 
sources. 

• Gauges, which displays values as a radial or arc gauge, based on a defined minimum and maximum measure 
setting. 



JasperReports Server has limited supportfor scatter charts created in some older versions. You can use 
the Ad Hoc views for those scatter charts to generate new reports, but you can't edit them. 


To select a new visualization type: 


1. In the Ad Hoc Editor tool bar, click the I*" icon to display the Select Visualization Type window. 



c] □ III III I 


Column Stacked Coljrrin 


PercentColumn Bar Stacked Ear PercentBar 


C ^ ^ rrent Select ion: C rossta b 

lor more Fields in Columnsor Rows 
lor more Measures in Columns or Rows 


Apply and Close 


Cancel 


Figure 5-3 Select Visualization Type Window 
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2. Click the type of visualization you want to apply to your report. The selected visualization type is outlined 
in blue. The Visualization Selector displays a description of the selected visualization and the number of 
fields and measures it uses. 

3. Click Apply and Close to use the visualization type. 


The following table describes the available visualization types, and mles (if any) affecting their use: 

Table 5-2 HTML5 Visualization Types 


Icon 

Description 

Ruies 

Data Grid 

Data grids dispiay vaiues from the data 
source in coiumns and rows as either indi- 
viduai or aggregate vaiues. 


o 

Crosstab. Compares one or more measures 
across multiple sets of related fields. 


n 

Tabie. Displays values corresponding to the 
columns and rows in the data source. 


Column and Bar 

Coiumn charts compare vaiues dispiayed as 
coiumns and bars. 


I 

III 

Coiumn. Multiple measures of a group are 
depicted as individual columns. 


I 

III 

Stacked Coiumn. Multiple measures of a group 
are depicted as portions of a single column 
whose size reflects the aggregate value of the 
group. 


I 

III 

Percent Coiumn. Multiple measures of a group 
are depicted as portions of a single column of 
fixed size. 


m 


Spider Coiumn. Multiple measures of a group 
are depicted as portions of individual "columns" 
along a spoked chart. 




Bar. Multiple measures of a group are depicted 
as individual bars. 




Stacked Bar. Multiple measures of a group are 
depicted as portions of a single bar whose size 
reflects the aggregate value of the group. 
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Icon 

Description 

Rules 

= 

Percent Bar. Multiple measures of a group are 
depicted as portions of a single bar of fixed size. 


Line and Area 

Line charts compare vaiues dispiayed as 
points connected by iines. 



Line. Displays data points connected with 
straight lines. 



Spiine. Displays data points connected with a 
fitted curve. 


¥ 

Spider Line. Displays data points connected 
with straight lines on a spoked chart. 


A 

Area. Displays data points connected with a 
straight line and a color below the line; groups 
are displayed as transparent overlays. 


■1 

Stacked Area. Displays data points connected 
with a straight line and a solid color below the 
line; groups are displayed as solid areas 
arranged vertically, one on top of another. 


■ 

Percent Area. Displays data points connected 
with a straight line and a solid color below the 
line; groups are displayed as portions of an 
area of fixed sized, and arranged vertically one 
on top of the another. 



Area Spline. Displays data points connected 
with a fitted curve and a color below the line; 
groups are displayed as transparent overlays. 


* 

Spider Area. Displays data points connected 
with straight lines and a solid color between the 
line and the center of a spoked chart; groups 
are displayed as transparent overlays. 
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Icon 

Description 

Ruies 

Dual and Multi-Axis 

Duai and muiti-axis charts compare two or 
more measures, using one charting time or 
muitipie charting types, with the charts iisted 
here. 


III 

Coiumn Line. Displays leftmost measures as 
columns, last measure as a line. 

• Requires two or more 

measures. 

• Measures must be placed in 
the Columns location. 

• Fields and dimensions can 
be placed only in the Rows 
location. 

Iff 

Stacked Coiumn Line. Displays leftmost 
measures as stacked bars, last measure as a 

line. 

• Requires three or more 

measures. 

• Measures must be placed in 
the Columns location. 

• Fields and dimensions can 
be placed only in the Rows 
location. 

ii^ 

Coiumn Spiine. Displays leftmost measures as 
columns, last measure as a spline. 

• Requires two or more 

measures. 

• Measures must be placed in 
the Columns location. 

• Fields and dimensions can 
be placed only in the Rows 
location. 


Stacked Coiumn Spiine. Displays leftmost 
measures as stacked columns, last measure as 

a line. 

• Requires three or more 

measures. 

• Measures must be placed in 
the Columns location. 

• Fields and dimensions can 
be placed only in the Rows 
location. 


Muiti-Axis Line. Displays each measure as a 
separate axis line. 

• Requires two or more 

measures. 

• Measures must be placed in 
the Columns location. 

• Fields and dimensions can 
be placed only in the Rows 
location. 
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Icon 

Description 

Ruies 


Muiti-Axis Spiine. Displays each measure as a 
separate axis spline. 

• Requires two or more 

measures. 

• Measures must be placed in 
the Columns location. 

• Fields and dimensions can 
be placed only in the Rows 
location. 


Muiti-Axis Coiumn. Displays each measure as 
a separate axis column. 

• Requires two or more 

measures. 

• Measures must be placed in 
the Columns location. 

• Fields and dimensions can 
be placed only in the Rows 
location. 

Time Series 

Time Series charts iiiustrate data points at 
successive time intervais. 



Line. Displays date and time data points 
connected with straight lines. 

• Requires a single date/time 
field in the Rows location. 

• Field must be set to the 
"day" group function. 


Spiine. Displays date and time data points 
connected with a fitted curve. 

• Requires a single date/time 
field in the Rows location. 

• Field must be set to the 
"day" group function. 

A 

Area. Displays date and time data points 
connected with a straight line and a color below 
the line; groups are displayed as transparent 
overlays. 

• Requires a single date/time 
field in the Rows location. 

• Field must be set to the 
"day" group function. 


Area Spiine. Displays date and time data points 
connected with a fitted curve and a color below 
the line; groups are displayed as transparent 
overlays. 

• Requires a single date/time 
field in the Rows location. 

• Field must be set to the 
"day" group function. 
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Icon 

Description 

Ruies 

Scatter and Bubble 

Scatter charts show the extent of correiation 
between the vaiues of observed quantities. 
Bubbie charts show the correiation between 
three measures, dispiayed as disks. 



Scatter. Displays first measure as the x-axis, 
the second measure as the y-axis. Other fields 
and dimensions in the column group become 
data points. 

• Requires exactly two 

measures. 

• Measures must be placed in 
the Columns location. 

•V* 

Bubbie. Displays first measure as the x-axis, the 
second measure as the y-axis, and the third 
measure determines the size of the disk. 

• Requires exactly three 
measures in the Columns 

location. 

• The measures cannot be 
placed between other fields. 

Pie 

Pie charts dispiay vaiues as siices of a 
circuiar graph. 


• 

Pie. Multiple measures of a group are displayed 
as sectors of a circle. 



Duai Pie. Multiple measures of a group are 
displayed as sectors of concentric circles. 

• Requires at least one 
measure and one field. 

• Fields must be placed in the 
Rows location. Only one 
field can be placed in the 
Rows location if it contains a 

measure. 

• Two fields can be placed in 
the Rows location if it 

contains no measures. 

• Multiple measures are 
allowed in the Rows 
location, but only one 
measure is allowed in the 

Columns location. 


Semi-Pie. Multiple measures of a group are dis¬ 
played as sectors of a half-circle. 
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Icon 

Description 

Ruies 

Range 

Range charts dispiay vaiues as heat maps. 


■ ■■■ 

■ ■■■ 
mmmm 
mmmm 

Heat Map. Individual values represented as col¬ 
ors. 

Non-OLAP: 

• One field, followed by one 
Measure, required in the 
Columns location. 

• One field required in the 
rows location. 

OLAP: 

• One Dimension level, 
followed by one Measure, 
required in the Columns 
location. 

• One Dimension level 
required in the Rows 
location. 

m 

Time Series Heat Map. Individual values 
across dates/times represented as colors. 

• One Measure required in 
the Columns location. 

• One Date/Time field 
required in the Rows 
location. 

• Only available for non-OLAP 
data sources. 

■: 

Duai Measure Tree Map. Displays data as 
color-coded rectangles; the size of each rect¬ 
angle is proportional to the first measure and 
the color represents the second measure. 

• Two Measures required in 
the Columns location. 

• One field required in the 

Rows location. 

• Only available for non-OLAP 
data sources. 

i! 

Tree Map. Displays data as rectangles; the size 
of each rectangle is proportional to the measure 
of the data it represents. The tree map displays 
nested rectangles when you have more than 
one field; the parent rectangle represents the 
leftmost measure while the nested rectangles 
represent the current level of aggregation. Click 
on a parent rectangle to drill down to the nest 
rectangles. 

• One Measure required in 
the Columns location. 

• One or more fields required 
in the Rows location. 

• Only available for non-OLAP 
data sources. 
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Icon 

Description 

Rules 

[=11 

iiSr 

Parent Tree Map. Displays data as nested rect¬ 
angles; the size of each rectangle is pro¬ 
portional to the measure of the data it 
represents. The nested rectangles represent the 
current level of aggregation while the larger rect¬ 
angle represents the parent level in the hier¬ 
archy. Click on a parent rectangle to drill down 
to the nest rectangles. 

• One Measure required in 
the Columns location. 

• Two or more Fields required 
in the Rows location. 

• Only available for non-OLAP 
data sources. 

Gauges 

Gauges dispiay vaiues as a portion of a radiai 
or arc gauge. 


0 

Gauge. Displays a single data value as a por¬ 
tion of a circle; the length of the circle is the 
data's numeric value proportional to the max¬ 
imum size defined for the measure. 

• One or more Measures 
required in the Columns 
location. 

• One or more Fields required 
in the Columns location. 

• Define the minimum and 
maximum sizes, color stops, 
and layout on the 

Appearance tab. 

0 

Muiti-ievei Gauge. Displays one or more data 
values as concentric circles; each circle rep¬ 
resents a measure and the length of the circle is 
the data's numeric value proportional to the max¬ 
imum size defined for the measures. 

• Two or more Measures 
required in the Columns 
location. 

• One or more Fields required 
in the Columns location. 

• Define the minimum and 
maximum sizes, color stops, 
and layout on the 

Appearance tab. 


Arc Gauge. Displays a single data value as a 
portion of a semi-circular arc; the length of the 
arc is the data's value proportional to the max¬ 
imum size defined for the measure. 

• One or more Measures 
required in the Columns 
location. 

• One or more Fields required 
in the Rows location. 

• Define the minimum and 
maximum sizes, color stops, 
and layout on the 

Appearance tab. 


5.1.6 The Filters Panel 

The Filters panel displays any filters defined for the view. You can set the filter values and see the resulting 
change in the Ad Hoc View panel. To hide the Filters panel, click the < button in the top left comer of the 

panel. Click the > button or “ icon on the minimized panel to expand it again. 
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For more information on working with filters, see “Using Filters and Inpnt Controls” on page 157. 


5.1.7 Saving an Ad Hoc View, Previewing and Creating a Report 

After you create a compelling table, chart, or crosstab, you can save the view in the repository for future use. 

To save an Ad Hoc view: 

151 

1. Hover your mouse over ^ . 

2. Select Save Ad Hoc View or Save Ad Hoc View As. 

3. Name the view as needed, and click Save. The view is saved in the repository. 

You can also save an Ad Hoc view as a report. Typically, a report is created when you want to: 

• See data in the interactive report viewer. 

• Perform additional formatting of the table data. 

• Embed the data content in a dashboard. 

Create a report from the view by selecting Save Ad Hoc View and Create Report; you can also create and 
mn a report directly from the repository. For more information, see ^‘Running or Creating a Simple Report” on 
page 58. When you mn the report, it is displayed as a JasperReport. 

5.1.7.1 Dependent Reports 

When you create a report from an Ad Hoc view, the report is considered “dependent” on that view. 

When you save an Ad Hoc view, some, but not all, of its changes appear in its dependent reports. For example, 
if you open an Ad Hoc view with a table and adjust the data level for its columns, the column changes will 
show up in previous reports created from that view. 

In cases where changes to an Ad Hoc view could cause errors in dependent reports, you should save the 
updated view with a different file name and create a new report. 


5.2 Working with Tables 

The following sections explain how to populate, edit, and format your table-type view. 
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Column 

Groups 




Click to add a title 


Opportunity 

Amount 

Probability 

BC 



Kobylin&kiWendad Comim - 2900 units, - Sally 

55,390.00 

70.00 

Smith-Hensley Electron - 2700 units - Will 

5,740.00 

85.00 

ChapIa-Cameron Machine - 3100 units - Will 

14,300.00 

75.00 

Kobylinski-Verdad Comm - 2400 units - Sally 

10,390.00 

75.00 

Smallwood-Chavez Telec - 2900 units - Will 

1,580.00 

70.00 

Smith-Hensley Electron - 1900 units - Will 

12,540.00 

85.00 

E Si M Tullao Electroni - 3100 units - Beth 

12,240.00 

50.00 

ChapI a-Cameron Machine - 3400 units - Will 

150,300.00 

35.00 

D 8l Z Kesslep Electron - 4000 units - Max 

140,330.00 

50.00 

Kobylinski-Verdad Comm - 4100 units - Sally 

1,190.00 

80.00 

Caro-Robertson Communi - 2600 units - Beth 

120,450.00 

80.00 

Smallwood-Chavez Telec - 1900 units - Will 

200,480.00 

80.00 

McDonald-Walter Electr - 2700 units - Max 

9,510.00 

60.00 

Smith-Hensley Electron - 2600 units - Will 

1,240.00 

85.00 

I Sl M Weyerhaeuser Tra - 3100 units - Chris 

45,210.00 

45.00 


Figure 5-4 Ad Hoc Editor’s Table View 


2.1 Using Fields in Tables 

Insert data into your table by adding fields. All available fields are listed in the Data Source Selection panel, 
on the left side of the Ad Hoc Editor. 

The available fields are divided into two sections in the panel: 

• Fields, which can be added to the table as columns or groups. 

• Measures, which are specialized fields that contain data values. 

To add fields and measures as columns to a table: 

1. In the Data Source Selection panel, click to select the field or measure you want to add to the table. Use 
Ctrl-click to select multiple items. 

2. Drag the selected item into the Columns box in the Layout Band. 

The field is added to the view as a column in the table. 

To remove a field or measure from a table: 

• In the Layout Band, click the x next to the field or measure’s name. 


2.2 Groups 


Groups allow you to create detailed data rows. For example, if you have a table that lists the suppliers for a 
national restaurant ehain, you ean group the suppliers by the State field. The suppliers’ names are then 
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rearranged so that all suppliers located in Maine, for instance, are located under a “Maine” header row; suppliers 
in Maryland are together under a “Maryland” header row, and so on. 

You can use multiple fields to make more specific nested groups. By adding a group based on the “City” field 
to the table described above, the restaurant suppliers are arranged by City within the State groups. Under the 
“Maine” header row, new header rows for Augusta, Bangor, and Portland are added, and the names of the 
Maine-based suppliers appear under their respective cities. Under the “Maryland” header row, header rows for 
Annapolis, Baltimore, and Silver Spring are added, and the names of Maryland-based suppliers appear under 
those headers, and so on. 

Only fields can be applied to a table as a group; measures cannot. 

Data is grouped in the table according to the order they have defined. You can change the order by dragging 
the groups into position if needed. 

To create a group: 

1. In the Data Source Selection panel, click to select the field you want to add to the table as a group. 

2. Drag the field to the Groups box in the Layout Band. 

The Ad Hoc view refreshes and displays the data grouped under a new header row. 



You can also add a group to the table by right-clicking a field and selecting Add as Group. 


To remove a group: 

• In the Layout Band, click the x next to the field’s name in the Groups box. 

To move a the grouping order up or down in a table: 

• In the Layout Band, drag the name of the group you want to move into its new position. 


.2.3 Summaries 

You can display summary data for any column in your table. Summary data may be in the form of various 
frmctions, such as: 

• Sum 

• Count 

• Distinct Count 

• Average 

For example, in a table with a list of stores, grouped by City and Country, you can display the number of stores 
in each City, and in each Country, using this function. 

By default, the summary function for each field is defined by the data source, OLAP, or domain definition. 

To add a summary to a specific column: 

• In the table, right-click the column you want to calculate a summary for, and select Add Summary. 

The summary information is added to the group header, or is added to the bottom of a column if no groups 
are included in the table. 

To remove a summary from a specific column: 

• In the table, right-click the column with the summary you want to remove, and select Remove Summary. 
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The summary information is removed from the table. 

To add or remove summaries from all columns: 
ft ^ 

• Click ^ and select Detailed Data. 


2.4 Column and Header Labels 

You can edit a column or header label directly in the Ad Hoc Editor. 

To edit a column or header label: 

1. On the Ad Hoc view panel, right-click the column or group header you want to rename. 

2. Select Edit Label from the context menu. The Edit Label window opens. 

3. In the text entiy box, delete the existing name and enter the new name. 

4. Click Submit. 

If space is at a premium, you can remove labels from the view. When you delete a label, it still appears when 
you look at the view in the Ad Hoc Editor, but does not appear when you mn the report. 

To delete a column or header label: 

1. On the Ad Hoc view, right-click the column or header label you want to remove. 

2. Select Delete Label from the context menu. 

To re-apply a label: 

1. Right-click the column or header label you want to replace. 

2. Select Add Label from the context menu. The Edit Label window opens. 

3. Enter the label name, if needed. 

4. Click Submit. 

2.5 Managing Column Size and Spacing 

You can change the size of, and spaces between, columns to manage the appearance of your table or use space 
more efficiently. 

To resize a column: 

1. In the Ad Hoc View panel, click to select the column you want to resize. 

2. Move the cursor to the right edge of the column. 

3. When the cursor changes to the resize icon (^~^), click and drag the column edge right or left until the 
column is the needed size. 

Spacers can be added to a table to arrange columns farther apart, or add margins to a table. 

To change the spacing between columns: 

1. In the Data Source Selection panel, in the Measures section, click Spacer. 

2. Drag the spacer into the Columns box in the Layout Band between names of the two columns you want 
to move apart. 

A spacer column, labeled ^ , appears in the table. 
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3. Repeat this action to add space as needed between columns. 

4. To remove a spacer, right-click the spacer column and select Remove from Table. 

To use spacers to create table margins: 

1. In the Data Source Selection panel, click to select Spacer. 

2. Drag the spacer into the Columns box in the Layout Band. 

3. Repeat until the margins are as wide as needed. 

4. Repeat the steps above, adding the spacer to the right edge of the table. 


.2.6 Reordering Columns 

You can move columns to the right or left to reorder data in your table. 

To reorder a column: 

1. In the Ad Hoc View panel, right-click the column you want to move. 

2. Select Move Right or Move Left from the context menu. 

5.2.6.1 Sorting Tables 

In the Ad Hoc Editor, you can sort the rows of a table by any field, using a number of different methods. 

To sort a table: 

A + 

1. Click ^ + . The Sort window appears. If the table is already sorted, the window shows the fields used. 

2. To add a field to sort on, double-click the field in Available Fields. The Available Fields panel now lists 
only fields not currently in Sort On. 

3. Select one or more fields to sort by. You can also use Ctrl-click to select multiple fields. 


4. Click 

5. To arrange the sorting precedence of the fields, select each field in the Sort window and click Move to top, 

A A ▼ ▼ 


Move up. Move down, or Move to bottom: 


, and 


6. To remove a field, select it and click 

7. Click OK. The table updates to display the rows sorted by the selected fields. 

You can also sort a table using the following methods: 

• Right-click a field in the Fields section of the Data Source Selection panel, and select Use for Sorting 
from the context menu. In this case, the table is sorted by a field that isn’t in the table; you may want to 
note the sorting fields in the title. 

• Right-click a column header on the Canvas of the Ad Hoc View panel, and select Use for Sorting from 
the context menu. 


If a column is already being used and you want to stop using it or change the sorting, right-click the 
column and select Change Sorting from the context menu. 
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5.2.7 


5.2.8 


5.2.9 


5.2.10 


Adding a Title 

1. Above the table, click the text Click to add a title. 

2. Enter the new table title in the text entry box. 

Changing the Data Format 

Yon can change the formatting for columns containing numeric data, such as dates and monetary amounts. The 
format is applied to all rows as well as the group- and view-level summaries. By default, non-integer fields use 
the -1,234.56 data format; integers use -1234. 

To change the data format for a column: 

1. In the Ad Hoc view, right-click the column header. 

2. Select Change Data Format from the context menu. 

3. Select the format you want to use. These options vaiy, depending on the type of numeric data contained in 
the column. 

The data in the column now appears in the new format. 


Changing the Data Source 

You may need to select a new data source for your table. This is a simple task, but you should keep in mind 
that all view data and formatting are lost when you select a new Topic, Domain, or OLAP connection. Any 

changes to the view are also lost if you navigate to another page using the browser navigation buttons, the main 
menu, or the Search field. To preserve changes, accept the current Topic or click Cancel. 

To change the table’s data source: 

1. At the top of the Data Source Selection panel, click ; and select Change Source. 

2. Select a different Topic, Domain, or OLAP connection. 

3. Click Table to apply the new data source. 

Click Cancel to return to the editor without changing the Topic. 


Controlling the Data Set 

You can control the data displayed in the table using the Canvas Options selector: ^ ^ . 

Your options are: 

• Detailed Data, which displays table detail only. For instance, in a table listing sales in dollars for all stores 
in a region for a given month, the amount sold by each store that month is displayed. 

• Totals Data, which displays the table totals only. In the table described above, the total amount of all sales 
at all regional stores that month is displayed. 

• Details and Totals, which displays both the individual store sales numbers, as well as the total sales 
numbers at the bottom of the store sales column. 

• Show/Hide Duplicate Rows, which displays only the distinct values in your table if you choose to hide 
the duplicate rows. See Showing Distinct Values for more information. 

Click to select the option you want to apply to your table. 
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2.11 Showing Distinct Values 

Tables sometimes contain duplicate values in multiple rows, making it difficult to find relevant data. You can 
choose to show only distinct values in your tables by choosing to hide duplicate rows, making the table shorter 
and easier to read. 

To show only the distinct values in a table, click on the Grid Detail Selector ^ ^ and choose Hide Duplicate 
Rows. 

When you choose to hide duplicate rows, all columns will be sorted in ascending order based on their distinct 
values by default, but columns explicitly sorted in ascending or descending order by the user will have higher 
priority. Sorting by hidden fields will have no effect. 


.3 Working with Charts 

Ad Hoc charts are a flexible, interactive way to explore your data graphically. You can choose different levels 
of aggregation for rows and columns, change a field from a column to a row, pivot the entire chart, hide chart 
values, and zoom in to see chart details. 
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Columrs 

Rows 


Store sal'Es m I store cost it I Mar^m it 



Figure 5-5 Ad Hoc Editor’s Chart View 

The following sections explain how to populate, edit, and format an Ad Hoc chart. Many tasks related to 
working with charts are identical (or very similar) to those for tables and crosstabs. For any tasks not discussed 
in this section, see the information in “Working with Tables” on page 109. 


.3.1 Using Fields and Measures in Charts 

You must add at least one measure to view a chart. Before any measures are added to the chart, the Ad Hoc 
Editor displays a placeholder with the legend displaying a single entry: Add a measure to continue. As you add 
measures, the editor displays the grand total of each measure in the chart. 

The initial display reflects only the measures you add; it does not change when you add fields or dimensions. 
For example, for each measure you add to a bar chart, you see a bar with the total value of the measure, 
regardless of how many fields you add. This means you can add, remove, and arrange measures and fields 
without waiting for the display to update. Once you have the fields and measures you want, you can use the 
sliders on the right to select the level of detail you want. See Figure 1-2 for more information. 

All available fields are listed in the Data Selection panel, as either standard fields or measures. 
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• Standard fields can be added to a column or a row. 

• Measures contain summarized values. They are typically numeric fields that determine the length of bars, 
size of pie slices, location of points (in line charts), and height of areas. They can be added to rows or 
columns, but must all be in the same target — that is, you can add one or more measures to the chart as 
columns, or add one or more measures to the chart as rows, but you cannot have one measure as a column 
and another as a row in the same chart. 

When creating a chart, keep in mind that row and column groups are arranged in hierarchies, with the highest 
member of the hierarchy on the left. For an Ad Hoc view based on an OLAP data source, you can change the 
order of distinct dimensions by dragging, but you cannot change the order of levels within a dimension. For an 
Ad Hoc view based on a non-OLAP data source, you can drag the field headings to rearrange the hierarchy; the 
highest level in a group should appear to the left; the lowest level in a group should appear to the right. For 
example, it doesn’t make sense to group first by postal code then by country, because each postal code belongs 
to only one country. 

To add a field or measure to a row or column: 

1. In the Data Selection panel, select the field you want to add to the chart as a group. Use Ctrl-click to 
select multiple items. 

2. Drag the selected item into the Columns or Rows box in the Layout Band. 

5.3.1.1 Setting Levels 

When you add a field or dimension to a column or row, a multi-level slider located at the top of the Filters pane 
allows you to set the level of aggregation to use for viewing the data. The number of fields or dimensions in the 
row or column determines the number of levels on the slider. Measures are not reflected in the slider. 


You cannot adjust levels on time series charts. 


The following figure shows the effect of the slider on a chart with one level of aggregation for both rows and 
columns. 


Columns 


Columns 

-a 
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Rows 



Figure 5-6 Effect of the Slider on a Chart 


I 


I 


I .ll 


I Store Sales Drink H Store Sales Food ■ Store Sales Non-Consumable 


To recreate this view: 


1 . 

2 . 

3 . 


Select Create > Ad Hoc View. 

In the Select Data wizard, select foodmart data for crosstab and click OK. 
Click to open the Visualization Selector. 


Ill 


4. Click ■■■ and then Apply and Close. 

5. Drag the following from the Fields panel to the Layout Band: 

• Store Sales from Measures to Columns. The view changes to show a column with the total. No slider 
is added for measures. 

• Product Family from Fields to Columns. The Data Level area is shown in the Filters panel, with a 
Columns slider added. 

• Date from Fields to Rows. A Rows slider is added to the Data Level area in the Filters panel. 

6. Use the sliders to see how the view changes. 

The sliders help you explore your data visually in a number of ways: 

• The slider reflects the hierarchy of the row or column groups, as determined by the order in which fields are 
arranged in the Layout Band. 

• Hovering over a setting on the slider shows the name of the field or dimension corresponding to that 
setting. 

• When you pivot a chart, slider settings are preserved and applied to the new target. For example, if you 
have the Row slider set to Month, the Column slider is set to Month when you pivot. See “Pivoting a 
Chart” on page 119 for more information. 

• When you remove the currently selected level from a row or column, the slider is reset to the total; when 
you remove a field that is not selected, the level remains the same. When you add a field or dimension to a 
row or column, the number of levels of the slider changes to reflect your addition. When you change the 
order of the fields in a row or column, the level on the slider changes to reflect the new level of the field 
corresponding to the selection. 

5.3.1.2 Changing Date Grouping 

If your chart includes data based on a date field, you can change the level of aggregation for the time data. To 
select the unit of time to chart: 

• Right-click on the date field in the Layout Band and select Change Grouping. Then select the time 
period you want from the cascading submenu. The view updates to reflect the new date grouping. 


Time Series charts can use only day, or smaller, intervals. 
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5.3.1.3 Changing the Summary Function of a Measure 

You can get a new view of your data by changing the summaiy function of a measure, for example, from sum to 
average. To select a new summaiy function for a measure: 

• Right-click on the measure in the Layout Band and select Change Summary Function. Then select the 
frmction you want from the cascading submenu. The view updates to reflect the new summary frmction. 

5.3.1.4 Pivoting a Chart 

You can pivot a chart in two ways: 

• Pivot the entire chart by clicking Q . The row and column groups switch places; slider levels are 
maintained. The following figure shows the effect of pivoting a basic column chart. 


Columns # Store Sales « 
Rows Date « 


Columns Date » 

Rows # Store Sales * 



Figure 5-7 Effect of Pivoting a Chart 

• Pivot a single group: 

• To pivot a single row group, right-click it and select Switch To Column Group. You can also move 
any field or dimension by dragging. You cannot drag a measure to a different group. 

• To pivot a single column group, right-click it and select Switch To Row Group. You can also move 
any field or dimension by dragging. You cannot drag a measure to a different group. 


.3.2 Formatting Charts 

You can control some aspects of how data points, field names and labels are displayed on your chart, including: 

• Whether data points are displayed. 

• Showing a measure name on charts including only a single measure. 

• Restricting the number of labels displayed. 

• Rotating the direction of label text. 

• Selecting the colors used by the chart. 

• Defining how gauges are displayed. 
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JasperReports Server also allows you to edit many of the chart's properties for cases when you want more 
control over the appearance of a chart. 

5.3.2.1 Displaying Data Points 

You can choose whether to display data points in your line, time series, or area chart. Data points can help users 
visualize chart data more accurately. 

To show data points on a chart: 

Cl 

1. In the Ad Hoc View panel, click the ~ icon. 

2. Select Chart Format... from the menu. The Chart Format window is displayed. 

3. Click the Appearance tab and select Show data points on line charts. 

4. Click OK. The name appears along the value axis. 

5. To remove data points from the chart, open the Appearance tab and deselect Show data points on line 
charts. 


Chart Format 


Axis Labels Appearance Advanced 


X Axis 


Interval between X-axis labels 1 


Rotation of X-axis labels -45 


Y Axis 

Interval between Y-axis labels 


Rotation of Y-axis labels 0 


Apply 


OK Cancel 


Figure 5-8 Chart Format Window 

5.3.2.2 Displaying the Measure Name on the Value Axis 

By default, in charts that include only a single measure, that measure's name is not displayed. For instance, if 
your measure displays the number of employees for each store in the region, that measure's label appears along 
the Y- (or value) axis, but the name of the measure ("Number of Employees" or similar) does not. You can, 
however, choose to display that measure name to clarity the information on your chart. 
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To show a measure name on the value axis: 

Cl 

1. In the Ad Hoc View panel, click the ~ ^ icon. 

2. Select Chart Format... from the menu. The Chart Format window is displayed. 

3. Click the Labels tab. 

4. Select Show measure name on value axis. 

5. Click Apply, then OK. The name appears along the value axis. 

6. To remove a measure name, open the Labels tab and deselect Show measure name on value axis. 

5.3.2.3 Restricting Label Display 

By default, eveiy field included in your chart has a label displayed along either axis. Measures will show up as 
numeric values, often along the Y axis, and fields being measured will show up as text along the X axis. On 
some charts - especially those with many included fields - these labels may overlap, crowd together, or become 
difficult to read. You can alleviate this problem by "stepping," or reducing, the number of labels displayed on 
your chart. 

To reduce the number of labels on your chart: 

CL 

1. In the Ad Hoc View panel, click the ~ ^ icon. 

2. Select Chart Format... from the menu. The Chart Format window is displayed. 

3. Click the Axis tab. 

4. In the Interval between X-axis labels numeric entry box, specify how often you want the axis label to 
appear. For instance: 

• To display eveiy second label, enter 2. 

• To display eveiy third label, enter 3, and so on. 

5. Repeat this process in the Interval between Y-axis labels numeric entry box. 

6. Click Apply, then OK. The labels appear as entered. 

7. To display every label, open the Axis tab and enter 1 in the numeric entry boxes. 

5.3.2.4 Rotating Label Text 

By default, labels on your chart are displayed horizontally. Multiple labels, or veiy long ones, can be difficult to 
read. You can change the direction of these labels, on both the X and Y axes, to improve chart readability. 

To rotate label text: 

<v 

1. In the Ad Hoc View panel, click the ~ ^ icon. 

2. Select Chart Format... from the menu. The Chart Format window is displayed. 

3. Click the Axis tab. 

4. In the Rotation of X-axis labels specify the degree of rotation to apply to labels. For instance: 

• To rotate labels clockwise 90 degrees, enter 90. 

• To rotate labels counter-clockwise 90 degrees, enter -90. 

• To rotate labels clockwise 45 degrees, enter 45, and so on. 

5. Repeat this process in the Rotation of Y-axis labels entry box for measures along the Y axis. 

6. Click OK. The labels are rotated. 

7. To return the labels to their original, horizontal position, open the Axis tab and enter 0 in the numeric 
entiy boxes. 
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5.3.2.5 Changing the Chart's Colors 

You can choose the colors of your chart by defining a series of colors for it to use. You can also choose the 
background’s colors. 

To choose the chart's colors: 

Cl 

1. In the Ad Hoc View panel, click the ~ icon. 

2. Select Chart Format... from the menu. The Chart Format window is displayed. 

3. Click the Appearance tab. 


Chart Format 


Axis 

Labels 

Appearance 

Advanced 


Series Colors 

+ Add Series Color 

Background Color's 

Chart: 

Plot: 

Line and Area 

Show data points on line charts 

Scatter and Bubble 

~i Show line on scatter charts 

Gauges 


Layout: | Best Fit ’ 



Min Value: 

0 

Max Value: 

200 


Decimal Places: 

1 

Suffix- 


T 



#FFFFFF 



TRATJSP 



Apply 


OK 


Cancel 


Figure 5-9 Appearance Tab 

4. Under Series Colors, click + Add Series Color to add the first color. 

The color picker button appears. The button will display a color and a corresponding Hex value. 

5. Click on the button to open the color picker window. 

6. Select the color you want to use. 
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7. Click outside the color picker window to close it. 

8. Click + Add Series Color to add additional colors. 



The order of the colors added to the chart is the order they appear in the series. 


Chart Format 


Axis 


Labels Appearance 


Series Colors 

Colon I 


#0D233A 

#417505 

#910000 

#F5A623 



#FFFFFF 



TRATJSP 



Advanced 


Color 2 
Colors 
Co lor 4 

+ Add Series Color 

Background Colors 

Chart: 

Plot: 


Line and Area 

^ Show data points on lire charts 

Scatter and Bubble 

f i: - - -1 1— 


Apply 


OK 


Cancel 


Figure 5-10 Appearance Tab with Multiple Colors in Series 

9. You can change the colors of the charts background and plot using the color picker buttons under 

Background Colors. 

10. When you are done adding colors to the chart, click OK. 

JasperReports Server reloads the chart with the new colors. 
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5.3.2.6 Changing the Display Settings for Gauges 

Gauges are circular and semi-arc charts. The length of the circle or semi-arc is based on a single data value in 
proportion to the minimum and maximum measurement amounts you define. 

Gauges have their own display settings on the Appearance tab, where you can select how they appear in the 
Ad Hoc view. You can specify the layout of the gauges on the canvas, the color stops, and the minimum and 
maximum values for the gauge's measure. 

The settings on the Appearance tab apply to all gauges in the Ad Hoc view. 

To edit a gauge's display settings: 

CL 

1. In the Ad Hoc View panel, click the ~ icon. 

2. Select Chart Format... from the menu. The Chart Format window is displayed. 

3. Click the Appearance tab. 


chart Format 


!.[_ ' Appearance | | Advanced | 

@ Shaw data points on line charts 

Scatter and Bubble 

Q Show line on scatter charts 

Gauges 


Layout; | Best Fit ^ 

] 


Mir Valuer O' | 

Max Value: 100 

Decimal Places: [~1 | 

Suffix:| 


Color Stop 1; 

#33A4FF 


Color Stop2: 

#33A4FF 


Color Stop 3: 

#33A4FF 


Color Stop4: 

#33A4FF 

□ 


Apply 


OK Cancel 


Figure 5-11 Gauge Settings on the Appearance Tab 

4. Under Gauges, select the layout for displaying the gauges. By default, the layout is Best Fit, which 
displays all of the gauges on the canvas in one or more rows. The gauges can also be displayed in a single 
vertical column or a single horizontal row. 

5. Enter the minimum and maximum values for the gauge's measure. For gauge and arc gauge charts, each 
measure added to the Ad Hoc view will be displayed as its own gauge and the gauge's circle or arc 
represents how a single data value in the data source compares to the maximum measure. For multi-level 
gauge charts, each measure is displayed as concentric circles in the gauge. By default, the minimum is 0 and 
the maximum is 100. The measures selected for the Ad Hoc view also determine whether to display the data 
as percentages or as numeric values. 
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6. Enter the number of decimal places to show as part of the value displayed in the gauge. The maximum 
number of decimal places you can specify is 8. 

7. Enter a suffix string if you want to label the value displayed in the gauge. 

8. Enter a value for each color stop for the gauge. Color stops define a gradient progression for the gauge's 
colors in the Ad Hoc view. The default color stop values are 0 . 2 , 0 . 5 , 0 . 7 , and 1 . 


You can have a maximum of four color stops in your gauge. Each color selected is the specific color 
displayed at the corresponding stopping point. The colors displayed in the gauges are based on where 
the gauge's value falls on the defined gradient. 


9. Click on the color picker button for each stop to open the color picker window and select the color. 

10. When you are done changing the colors, click OK. 

JasperReports Server reloads the Ad Hoc view's gauges with the new display settings. 


5.3.2.7 Changing the Chart's Appearance Using Advanced Formatting 

The Advanced tab on the Chart Format window gives you more control over the appearance of an Ad Hoc 
chart by allowing you to edit certain chart properties. For example, you can specify a list of colors for the chart, 
change the position of the legend, choose whether to display data values in the chart, and much more. You can 
find a full list of supported commands by clicking the More Information link on the Advanced tab or 
browsing to the Advanced Chart Formatting page on the Jaspersoft Community Site. 

To edit the chart's properties: 

<v 

1. In the Ad Hoc View panel, click the ~ ^ icon. 

2. Select Chart Format... from the menu. The Chart Format window is displayed. 

3. Click the Advanced tab. 

4. Click Add New Property. 

5. In the Property field, enter the chart property you want to format and then enter the value(s) for the 
property. For instance: 

• To format the chart's colors, enter colors for the property and a comma-separated list of colors in 
brackets for the values, such as ["red", "blue", "green", "magenta", "purple", "black", "yellow"]. 

• To change the vertical alignment of the legend, enter legend.verticalAlign for the property and "top" or 
"bottom" or "center" for the value. 

• To display data values on the chart, enter plotOptions.series.dataLabels.enabled for the property and 
tme for the value. 

Click the More Information link to see a list of the properties you can edit. 



The Ad Hoc Designer does not validate the property name or values. The chart will ignore any invalid 
property you enter. 


6. Click ^ to save the property formatting. 

7. Click OK. The chart is updated with the new formatting. 

8. To remove the formatting, open the Advanced tab and click DD next to the property you want to remove. 
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.3.3 Interacting with Charts 

Once you have chosen rows and columns and selected the type of chart you want, you can further explore your 
data using interactive features such as bmshing an area of the chart to zoom in or clicking on a legend to hide 
the members of a group. 

5.3.3.1 Zooming 

Zooming lets you view a specific area of a chart more closely. Zooming can also be helpful when the labels at 
the bottom of a chart are difficult to read, because only the labels corresponding to the selected area are 
displayed. 


Zoom is a viewing feature of the Ad Hoc Editor. When you save an Ad Hoc view, or create a report from an 
Ad Hoc view, the zoom is automatically reset to show the whole chart. 


To zoom in on an area of a chart: 

• Click and drag or bmsh the area you want to zoom in on. As you are dragging or bmshing a pale blue area 
indicates your selection. When you release the mouse button, the view zooms in on the area you selected. 

To view the whole chart again: 

• Click Reset zoom at the upper right of the canvas. 

The following images show a bar chart before and after zooming: 



DF Cuerrero Jalisco Mexico Sinaloa Veracruz Yucatan Zacatecas CA OR WA 

Mexico USA 


S Store Sales B Store Cost 


Figure 5-12 Selecting a Zoom Area 
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Drink Food Non-Consumable Drink Food Non-Consumable 

Sinaloa Veracruz 


B Store Sales B Store Cost 


Figure 5-13 Area After Zooming 

5.3.3.2 Hiding Group Members 

Use the legends below the chart to hide or show group members. 

• To hide a group member, click the member name in the legend below the chart. The member is removed 
from the chart and the legend is grayed out. 

• To unhide a group member that has been hidden, click the grayed-out legend for the member. 



Figure 5-14 Hiding a Group Member 


Hidden members are a view feature of the Ad Hoc Editor. When you save an Ad Hoc view, or create a 
report from an Ad Hoc view, the chart is automatically reset to show all members. 


.4 Working with Standard Crosstabs 


This section describes crosstabs based on Topics and Domains. For information about crosstabs based 
on OLAP connections, refer to “Working with OLAP Connection-based Crosstabs” on page 132 and 
“Working with Topics” on page 169. 


Crosstabs have different data, layout, and format options than tables or charts. 
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Figure 5-15 Ad Hoc Editor’s Standard Crosstab View 

If you selected Crosstab when you created a view, as described in ‘‘Ad Hoc View Types” on page 95, the 
following sections explain tasks specific to your crosstab development. 


5.4.1 Using Fields in Crosstabs 

Fields can be added to crosstabs as row groups or column groups. Measures can be added to crosstab rows or 
columns as well, but all measures must be included as either a row or a column - that is, you can add one or 
more measures as columns, or add one or more measures as rows, but you cannot have one measure as a column 
and another as a row in the same crosstab. 

5.4.1.1 Crosstab Rows and Columns 

When creating a crosstab view, keep in mind that row and column groups are arranged in hierarchies. Drag the 
group headings to rearrange the hierarchy; you can also right-click a heading and select a Move option from the 
context menu or press the cursor keys. Rearranging the groups may change the preview data in the editor. 

To add a field or measure to a crosstab group: 

1. In the Data Source Selection panel, click to select the field(s) you want to add to the crosstab as a group. 
Use Ctrl-click to select multiple items. 

2. Drag your selection into the Columns or Rows box in the Layout Band. 

5.4.1.2 Crosstab Measures 

Measure labels are displayed in the crosstab based on their status as a row or column: 

• Measures included as rows appear in the crosstab below the Measures heading. 

• Measures included as columns appear in the crosstab to the right of the Measures heading. 

You can right-click a measure in the crosstab to open a context menu that provides these options: 

• Change Summary Calculation 

• Change Time Balance Calculation 
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• Change Data Format 

• Remove From Crosstab 

• Create Filter 

• Move Up or Move Down or Move Left or Move Right 

Measures are arranged in cells. You can add any number of measures. All the measures appear together in eveiy 
cell. To rearrange the measures, drag them in the measure label area. 

5.4.1.3 Pivoting 

You can pivot a crosstab in two ways: 

• Pivot the entire crosstab by clicking Q . The row and column groups switch places. For more 
information, see ^‘Creating a View from a Domain” on page 164. 

• Pivot a single group: 

• To pivot a single row group, right-click it and select Switch To Column Group. 

• To pivot a single column group, right-click it and select Switch To Row Group. 



Pivoting removes any custom sorting applied to headings in your crosstab. It does not affect column or 
row sorts. 


5.4.1.4 Slicing 

The slice feature lets you keep or exclude group members in a crosstab. To slice, right-click a group member and 
select: 

• Keep Only to remove all groups except the selected one from the crosstab. 

• Exclude to remove this group from the crosstab. 

Use Ctrl-click and Shift-click to select multiple groups to keep or exclude. 


You can select multiple row groups or multiple column groups; you can't slice by both row groups and 
column groups at once. Compare slice to drill-through, drill to details, and filtering. 


For more information about filtering, see “Using Filters and Input Controls” on page 157. 


5.4.1.5 Summarizing 

All row and column groups are summarized automatically: 

• To turn off a group summaiy, right-click any heading in the group and select Delete Row Summary or 
Delete Column Summary from the context menu. To reapply the summary, right-click the heading and 
select Add Row Summary or Add Column Summary. 


The Delete Summary option is available only for the outermost group on either axis (that is, either the 
outermost row group or the outermost column group) 


To select the summary ftmction and data format for a measure, right-click the measure label and select from 
the context menu. Note that you can’t change the summary function on custom fields that calculate percents 
(Percent of Total, Percent of Column Group Parent, and Percent of Row Group Parent). 

The summary functions for numeric fields are Sum, Average, Maximum, Minimum, Distinct Count, and 
Count All. Distinct Count is the number of different items in the row or column; Count All is the total 
number of items. For instance, if there are 3 widgets of type A and 3 widgets of type B, Distinct Count is 2 
and Count All is 6. 
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5.4.1.6 Collapsing and Expanding Members 

By default, the editor displays each row and column group of a crosstab in a collapsed state. This means you 
can see the totals for the group, but not the measures for its individual members. To see measures for a group’s 
members, right-click the group label and select Expand Members. 

When a group’s members are expanded, select Collapse Members from the same menu to hide the measures. 
Collapsing an outer group also collapses its inner groups. The Expand Members and Collapse Members 
options are available only for outermost groups, or for inner groups nested in an expanded outer group. 

When you collapse a group, its summary is automatically displayed; this prevents invalid crosstab layouts in 
which there is nothing to display for some totals if the summary has been deleted previously. 

5.4.1.7 Merging and Unmerging Crosstab Cells 

By default, the editor merges cells containing the same data into a larger, single cell to make the crosstab data 
easier to read. The following image shows a crosstab with merged cells. 

To display all of the individual cells in the crosstab instead of merged cells, hover over ^ and select 
Unmerge crosstab cells. The following image shows a crosstab with unmerged cells. 

To merge the crosstab cells, hover over ^ and select Merge crosstab cells. 

5.4.1.8 Sorting 

By default, the rows and columns of crosstabs are sorted in alphabetical order of the group names. 

To sort your crosstab: 

• Right-click the heading you want to use for sorting and select one of these options: 

• Sort Ascending 

• Sort Descending 

• Don't Sort 

The crosstab is updated to reflect your sorting option. A blue dot appears in the context menu next to the 
currently applied sort option. 

When the crosstab includes more than one row group or more than one column group, the inner groups are also 
sorted according to your selection. Only one measure can be used for sorting at any one time; changing the sort 
order for another measure resets all others to the default. 

To filter top or bottom N values: 

You can filter the numeric data shown in a crosstab to show only the rows with the top or bottom N values, 
where N is a number that you specify. For example, you can filter a crosstab to display only the top 10 values 
in a column. 

1. Right-click the heading you want to use for filtering and select one of these options: 

• Filter Top N Values 

• Filter Bottom N Values 

• Don't Filter Values 

2. Enter the number of values you want to show in the crosstab. 

3. Select whether to show an aggregate of the unranked values in the crosstab. 

4. Select whether to apply the filter across all row groups. 

5. Click OK. 
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The crosstab is updated to reflect your filter option. The icon appears in the heading when filtering a 
column for the top N values, while the icon appears when filtering for the bottom N values. A blue dot 
appears in the context menu next to the currently applied filter option. Only one measure can be used for 
filtering at any one time; changing the filtering or sort order for another measure resets the filtered column. 

5.4.1.9 Changing How Totals Are Calculated Using Time Balance 

By default, crosstabs show the Totals of numeric values as the sum of the values in a column. For example, if 
the crosstab view displays product sales grouped by month, the crosstab displays the total sum sold during those 
months as the Totals value. 

You can change the data that the crosstab displays as the Totals value for a period of time using the Time 
Balance options. These options allow you to change the Totals to display the first and last numeric values for 
the period. For example, if you want to see the number of products left in your inventoiy at the end of a certain 
time period, use the Time Balance Last option and the Totals fields will display the last numeric value entered 
for the time period. If you want to see the number of products in your inventory at the beginning of the time 
period, use the Time Balance First option. 


Changing the time balance calculation requires the crosstab to use the Date field. You cannot drill 
through the data when using a Time Balance option otherthan the defaulter when using Day ofWeekfor 
the grouping. 


To change the totals calculation using time balance: 

1. In the Ad Hoc view, right-click the column or row header. 

2. Select Change Time Balance from the context menu. 

3. Select the option you want to use. You can select one of the following: 

• Time Balance Default. This option displays the sum of all the numeric data for a period of time as the 
Total value. 

• Time Balance First. This option displays the first numeric value for a period of time as the Total value. 
For example, if the period of time is a month, the crosstab will display the first numeric value entered 
for the month. 

• Time Balance Last. The option displays the last numeric value for a period of time as the Total value. 
For example, if the period of time is a month, the crosstab will display the last numeric value entered 
for the month. 

The crosstab is updated to show the new Total values. 

5.4.1.10 Changing the Data Format 

You can change the formatting for rows and columns containing numeric data, such as dates and monetaiy 
amounts. By default, non-integer fields use the -1,234.56 data format; integers use -1234. 

To change the data format for a column: 

1. In the Ad Hoc view, right-click the column or row header. 

2. Select Change Data Format from the context menu. 

3. Select the format you want to use. These options vaiy, depending on the type of numeric data contained in 
the column. 

The data in the column or row now appears in the new format. 
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5.4.1.11 Resizing and Layout 

Many of the layout and formatting options that are set manually in tables are set automatically in crosstabs. In 
particular, row and column sizes are fixed and no spacer is available. 

5.4.1.12 Drilling Through Data 

Drill-through functionality is available for crosstab data. A drill-through table displays the supporting details for 
the selected roll-up value. 

To view the drill-through table for a value in your crosstab: 

• Click hyperlinked data to display additional columns from that specific fact data. 

By default, the drill-through table opens in its own window or tab, depending on your browser settings. 


.5 Working with OLAP Connection-based Crosstabs 

An OLAP connection is a definition for retrieving OLAP data for use in Ad Hoc views and reports. An OLAP 
connection is either a direct Java connection (Mondrian connection) or an XML-based API connection (XML/A 
connection). You must create OLAP client connections in order to use this functionality, which may be 
restricted by your license. For more information on creating OLAP client connections, as well as other 
administrative tasks regarding OLAP, refer to the TIBCO Jaspersoft OLAP User Guide. 

The Ad Hoc Editor displays a more focused tool bar when your Ad Hoc view is based on an OLAP connection. 
It contains a subset of the options available in the standard tool bar, including Display Mode, Redo, Undo All, 
Switch Group, Display Options, and View MDX Queiy. For a description of these options, see Table 5-1. 
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Figure 5-16 Ad Hoc Editor’s OLAP Connection-based Crosstab View 


. 5.1 Dimensions and Measures 

When you create a view based on an OLAP connection, the cube metadata defined in the connection’s OLAP 

schema is automatically applied to your data: the dimensions and measures in the cube are shown in the Data 

Source Selection panel. 

Dimensions and measures describe your data in terms of these organizing principles and facts: 

• Dimension: A categorization of the data in a cube. For example, a cube that stores data about sales figures 
might include dimensions such as time, product, region, and customer’s industiy. A dimension is a 
hierarchical series of relationships in which each level has a parent and may also have children. Note that a 
level is a particular location within the dimension, whereas a member is a specific data element at a 
particular level. For example, if the dimension is Geography, then one of its levels might be Country; at the 
Country level, USA might be a member. 

Some dimensions include a special level at the top of the hierarchy that includes eveiy level in the 
dimension. This All member is used to display the summarized data across the dimension. The All member 
of dimensions is a common feature in many OLAP solutions. 

• Measure: A field that displays the facts that constitute the quantitative data in a cube. For example, a cube 
that stores data about sales figures might include measures such as unit sales, store sales revenue, and store 
sales cost. 
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The items in the Dimensions section of the Data Source Selection panel may appear in a multi-level tree 
stmcture. You can add the entire dimension tree, or any sub-trees, to your crosstab by dragging the top-level 
name into the Layout Band. Individual items can be added to the crosstab in the same manner. 

Items in the Measures section are organized into a single-level list. Any calculated measures are indicated by a 
calculation icon . 

When working with OLAP connections, the Layout Band at the top of the Ad Hoc View panel allows you to 
drag and drop dimensions and measures into the crosstab. As you add columns and rows, the crosstab 
automatically builds on the panel. In the Columns and Rows fields, each item in your crosstab is represented 
as a token; drag tokens left and right to change their position on an axis or drag them between the fields to 
pivot them. 

The cube metadata applied to your view provides stmcture to your crosstab: you can add a dimension with any 
number of levels, but it must follow the hierarchy defined in the cube. For example, if a dimension’s levels are 
Countiy, State, and City, you can place any one of them in the crosstab, but if you add two or more, their order 
(defined in the OLAP schema) is enforced. For example: 


Possible 

Impossible 

Country, State, City 

State, Country, City 

Country, City 

City, Country 

State, City 

City, State 

Country, State 

State, Country 


In addition, you can’t mix members from different dimensions. For example, consider a crosstab that includes 
both a Geography dimension (Country, State, and City) and a Time dimension (Year, Quarter, and Month): you 
can’t insert the Year level between the Country and State levels. The levels of each dimension are always kept 
together. 

All measures in the crosstab must be either rows or columns. You can’t have measures on both axes at the same 
time. To move measures between dimensions, right-click and select Switch To Column Group or Switch To 
Row Group. All the measures move to the other axis. 


5.2 Drilling Through Data 

Drill-through functionality is available for crosstab data. A drill-through table displays the supporting details for 
the selected roll-up value. 

To view the drill-through table for a value in your crosstab: 

1. Click hyperlinked data to display additional columns related to that information. 

2. Use the page controls to navigate the table. 

The drill-through table opens in its own window or tab, depending on your browser settings. 


5.3 Sorting 

Like standard crosstabs, the rows and columns of an OLAP crosstab are sorted in alphabetical order of the group 
names. 
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To change the sorting of your OLAP crosstab: 

• Right-click the heading you want to use for sorting and select one of these options: 

• Sort Ascending 

• Sort Descending 

• Don't Sort 

The crosstab is updated to reflect your sorting option. A blue dot appears in the context menu next to the 
currently applied sort option. 

When the crosstab includes more than one row group or more than one column group, the inner groups are also 
sorted according to your selection. Only one measure can be used for sorting at any one time; changing the sort 
order for another measure resets all others to the default. 


5.4 Viewing the MDX Query 

You may want to view the MDX queiy created for the OLAP connection used with your crosstab, to verify 
what data users are hitting. If this option is enabled, you can do this in the Ad Hoc Editor with the View 
Query button. 

The queiy is read-only, but can be copied to a document for review. 

To view the MDX query: 

• In the tool bar, click . The View Query window opens, displaying the query. 

5.5 Working with Microsoft SSAS 

The Ad Hoc Editor allows you to view data from Microsoft SQL Server Analytical Services (SSAS) to populate 
views and reports with multi-dimensional OLAP data. XML/A connections that point to your SSAS data are 
listed with the other OLAP connections when you create an Ad Hoc view, as in the following chart example. 
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Figure 5-17 Search Results Listing 

For details, refer to the TIBCO Jaspersoft OLAP User Guide. 


.6 Calculated Fields and Measures 

You can create new fields or measures in an Ad Hoc view by applying formulas to a view’s existing fields and 
measures. For example, consider a view that includes both a Cost and a Revenue field. You could calculate the 
profit for each record by creating a custom field that subtracts the Cost field from the Revenue field. For 
example, you can divide the Profit custom field in the previous example by the Revenue field to express each 
record’s margin as a percent. 
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If you have installed the samples, the Ad Hoc view 10. Calculated Fields and Measures includes examples 
of calculated fields (shown by the icon or calculated measures (shown by the icon P^). You can explore 
their formulas by right-clicking the field or measure name and selecting Edit. You can also create tables, charts, 
or crosstabs to see how these calculations work in views. 


.6.1 Overview of the Calculated Fields Dialog Box 

The Calculated Field or Calculated Measures dialog box allows you to create a calculated field or measure 
and set its summaiy function. This section describes the hmctionality available in this dialog box. 

To open the calculated fields dialog box for Ad Hoc views: 

1. Create or open an Ad Hoc view. 

2. Open the calculated fields dialog using one of these methods: 

• Click at the top right of either the Fields section or the Measures section of the Data Source 
Selection panel and select Create Calculated Field... from the context menu. 

• Right-click on an existing calculated field (shown by the icon ) or calculated measure (shown by the 
icon fX) 

and select Edit. 

The dialog displays a text field for the name and two tabs. Formula Builder and Summary. 


The following are reserved words and cannot be used as field names: AND, And, and, IN, In, in, NOT, 
Not, not, OR, Or, or. Names containing these strings, such as "Not Available", can be used. 


5.6.1.1 The Formula Builder Tab 

The Formula Builder tab is where you create the formula for your calculated field or measure. This tab includes 
the following: 

• Formula entry box — Shows the current formula for calculating your field or measure. You can edit the 
formula by typing directly in the panel. You can also add Fields, Measures, and Functions by double¬ 
clicking them. Click the buttons below the Formula field to add operators. Formulas must use the following 
syntax: 

a. Labels for fields and measures must be in double quotes ("): "Customer ID", "Date ordered". 

b. Text must be in single quotes ('): 

c. Levels must be in single quotes ('): 'ColumnGroup', Total’. See Levels in Aggregate Functions for more 
information about levels. 

For more information on syntax, see Calculated Field Syntax. 

• Operator buttons — Click these buttons to insert the operator in the Formula entiy box. For more 
information on operators, see Operators in Ad Hoc Views 

• Fields and Measures — Lists all the fields and measures currently in your Ad Hoc view, including any 
calculated fields or measures you have already created. 

• Functions — Lists all the available fimctions you can use in your formula. For more information, see 
Calculated Field Reference. 

• Function Description panel — Gives a brief description of the function selected in the Functions list, if any. 
The sample inputs are intended to be as descriptive as possible. See Calculated Field Reference for the 
precise syntax each fimction requires. 

• Show arguments in formula checkbox — When this checkbox is selected, double-clicking a fimction name 
in the Functions list adds the full description to the Formula entry box; when the checkbox is not selected, 
double-clicking a function name adds only the function. For example, double-clicking Round adds Round 
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("NumberFieldName", Integer) when the checkbox is selected, and adds Round () when the checkbox 
is not selected. If you select this checkbox, you can double-click on a string, such as NumberFieldName, 
and then replace it by double-clicking a name in the Fields and Measures list. 

• Validate button — Checks the formula for syntax errors, such as missing parentheses or quotes. Your 
calculated field or measure must be valid before you can create it. Syntax validation does not guarantee that 
your formula will give the results you want. 

5.6.1.2 The Summary Tab 

Summaries show a result applied to all data values. For example, for a numeric fields such as Cost, the summary 
value might be the sum of all the costs; for a text field such as Customer Name, the summary value might be the 
count of all customers. The Summaiy tab lets you set the default summary function for your calculated field or 
measure. 

• Calculation list — Displays allowed summaiy functions for your calculated field or measure. The available 
options depend on the data type of the calculation. See Summary Calculations for more information. 
Depending on your selection, you may see additional options: 

• Custom selection — Displays the same options available in the Formula Builder tab, including the 
Formula entiy box, operator buttons. Fields and Measures list. Functions list, and Validate button. You 
use these options to build a formula for your custom summaiy. However, for summaries, you are limited 
to aggregate fimctions, that is, functions that operate on all the values in your field. For example. Sum 
and Mode are valid summary functions, because they use all available field values to get a result. Round 
is not a valid summaiy function, because it operates on a single value at a time. See Summary 
Calculations for more information. 

• Weighted Average — Displays a Weighted On drop-down list, which allows you to choose another 
field or measure to use as the weight for the average. 


.6.2 Creating a Calculated Field 

To create a calculated field: 

1. First, create the Ad Hoc view to use. To do this, select Create > Ad Hoc View from the menu. The Select 
Data wizard appears. 

2. Click ^ and navigate to Domains. 

3. Select Supermart Domain. Click Choose Data. The Data Chooser window appears. 

4. In the Data Chooser window, double-click Sales to select it and click OK. A new Ad Hoc view opens. 

5. In the Ad Hoc view, click ; at the top right of the Fields section and select Create Calculated Field... 
from the context menu. The New Calculated Field dialog box appears, displaying the Formula Builder. 
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New Cialcul^ted Reid 

Field Name: 
Volume Ti e r 


Formula Builder 


Su m m a ry Calc ulatio n 


Formula: 

IFC'Unit Sales 2013" IN (0:100), 'Low', 'High'} 


+ - * / % 


AMD OR NOT IM =!=><>= <= 


Fields and Measures:: 


Functions: 


S Balad Bar 


123 Shelf Depth 


123 Shelf Height 


123 Shelf Width 


Afa( State 


Afat State/Province 

1 


123 Store 'Oast 2013 


Afai Store Name 


E 1 apse dSe mis 

Elapsed Weeks 

Elapse dVea ns 

EndsWith 

m 

y 

Integer 


IsMull 


Length 

T 


Qi Validation successful! 


Function Description: 

IF 

Returns second argument if first argument is true; 
ret urns optional third argument if first argument is 
false. 

rF{"BooleanFieLdNaine"j TrueCalc^ FalseCalc) 


\^\ Show arguments in formula 


Create Field 


Cancel 


Figure 5-18 Formula Builder Tab in New Calculated Measure Dialog Box 

6. Enter Volume Tier for the Field Name. 

Creating the formula: 

This section shows how to create a simple text formula that says Low when the Unit Sales amount is under 100 
and High otherwise. 

Formulas must use the following syntax: 

a. Labels for fields and measures must be in double quotes ("): "Customer ID", "Date ordered". 

b. Text must be in single quotes ('): 

c. Levels must be in single quotes ('): 'ColumnGroup', Total’. 

7. Make sure Show arguments in formula is selected. 

8. Now create the formula. Double-click ILQ in the Functions list. 

Because Show arguments in formula is selected, if ("BooleanFieldName", TrueCalc, FalseCalc) 
is entered in the Formula Builder. 

9. Double-click BooleanFieldName to select it, then double-click Unit Sales 2013 in the Fields and 
Measures list. 

The Formula Builder displays IF ("Unit Sales 2013", TrueCalc, FalseCalc). 
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10. Edit the expression in the Formula Builder to read as follows: IF ("Unit Sales 2013" in (0:100), 

'Low ', 'High') . 

11. Click Validate to verify that the formula does not have any syntax errors. 

Creating a summary calculation: 

The Ad Hoc Editor creates a default summaiy calculation based on the type of formula you have entered. This 
section shows how to select a different summaiy function. 

12. Click the Summary Calculation tab. 


New CslcuLsted Reid 


Field Name: 


Volume Tier 


Formula Builder | 

Summary Cakulation 


Calculation: 



Mode 


T 


Create Field 


Cancel 


Figure 5-19 Summary Tab in New Calculated Measure Dialog Box 

13. Select Mode from the Calculation menu. 

14. Click Create Field. 

The calculated field appears in bold text at the bottom of the list of available fields. A special icon 
indicates it is a calculated field 

If you have installed the samples, the Ad Hoc view 10. Calculated Fields and Measures includes examples 
of calculated fields and measures (indicated by /*). You can explore their formulas by right-clicking the field or 
measure name and selecting Edit. You can also create tables, charts, or crosstabs to see how these calculations 
work in views. 


.6.3 Planning and Testing Calculated Fields and Measures 

When you are creating calculated fields and measures, you may need to follow an iterative process: first create 
your new fields and measures, then view the results, and finally adjust as needed. The following practices can 
help: 

• Reduce the size of your data set — To speed field creation and testing, reduce the size of your working data 
set in the following ways: 

• Select Sample Data from the drop-down menu in the Ad Hoc tool bar. 

• Create one or more filters. This is especially useful for tables, which display all data by default. 

• Limit the number of fields and measures you add to your test reports to restrict the number of summary 
levels to one or two. 
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• Create one or more formulas, as described in Creating a Calculated Field. 

• After you have created your fields and measures, add them to a table or crosstab in your view and verify 
that they behave as you expect. You may need to edit your fields to get the desired behavior. See Creating 
a Calculated Field for more information. 

In addition, keep the following in mind when creating calculated fields: 

• When you create a calculated field, it appears at the bottom of the list. 

• Calculated fields that use aggregate functions cannot be added to groups and should not be used as filters. 

• By default, the Ad Hoc Editor supports only two decimal places. If the calculated fields return data that are 
significant to the third decimal place, you can add new masking options by editing configuration files. For 
more information, refer to the TIBCO JasperReports Server Administrator Guide. 

• You can’t delete a calculated field that is in use; these fields have their name in italics. 

• If the calculated field is used in the Ad Hoc view panel, remove the calculated field from the Ad Hoc 
View panel and then delete it from the Data Source Selection panel. 

• If the calculated field is the basis of another field, you can’t delete it until you delete the one that 
builds on it. 

• If the calculated field uses an item that was removed from the data source, the Ad Hoc Editor displays 
an error message. You will need to either edit or delete the calculated field. 


.6.4 Calculated Field Reference 

This section lists all functions that can be used to create calculated fields and measures in Ad Hoc views. For 
details of the supported syntax, see Calculated Field Syntax. 


These functions are available for calculated fields and measures in Ad Hoc views only. See TIBCO 
JasperReports Server Data Management Using Domainstor supported operators and functions in 
Domains. 


The examples in this section indicate correct syntax, but are not necessarily associated with an Ad Hoc view. If 
you have installed the Jaspersoft samples, the Ad Hoc view 10. Calculated Fields and Measures includes 
examples of calculated fields (shown by the icon i''^) or calculated measures (shown by the icon . You can 
explore their formulas by right-clicking on the field or measure name and selecting Edit. You can also create 
tables, charts, or crosstabs to see how these calculations work in views. 

Abso lute (Numer/cExpress/on) 

Returns the absolute value of a number or field, that is, the non-negative value of the number. 

Examples: 

Absolute ("Transaction Amount") — Shows the magnitude of each transaction, regardless of whether the 
transaction is positive or negative. 

"Commission Rate" Absolute ("Transaction Amount") —Computes a positive commission on all 

transactions, regardless of whether the transaction is positive or negative. 

Attribute('Sfr/ngExpress/onf, ['Sfr/ngExpress/on2' ]) 

Given the name of an attribute as the first argument and an optional category as the second argument, returns 
the attribute's current value as a String. If a category is specified (USER, TENANT, or SERVER), returns a 
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categorical attribute; returns a hierarchical attribute otherwise. This value can be cast to a different datatype 
using one of the casting functions available in Ad Hoc: Boolean (), Date (), Decimal (), integer (), Time (), 
or Timestamp ( ). It is your responsibility to ensure the attribute's format and values work correctly with your 
Ad Hoc view. See the TIBCO JasperReports Server Administrator Guide for more information about creating 
and using attributes. 

Example: 

Attribute('my_attribute’) 


Average(NumericExpression[,'Level']) 

Returns the average value of a measure or numeric field, based on an optional level. Null values are not 
included. See Levels in Aggregate Functions for more information. 

Example: 

Average("Salary", 'RowGroup') 


Boolean {'StrinsExpression') 

Casting function that takes a String expression and converts it to a Boolean data type. The String can be any 
expression that returns a supported string, including a field value or an attribute retrieved with the Attribute 
0 function. The Boolean () function requires one of the following Strings: tme, false, Tme, False, TRUE, or 
FALSE. Other Strings will return an error. 

Examples: 

Boolean('true') 

Boolean(Attribute('my_boolean_attribute')) 

Case (Expression, ValueExpressionI y ReturnExpressionI y ValueExpressionly /?efurnExpress/on2 
ValueExpressionNy ReturnExpressionN][yDefaultReturnExpression ]) 

Takes 2N+1 or 2N+2 arguments: an expression followed by one or more value expression/retum expression 
pairs, with an optional final return expression. Compares the expression in the first argument to each value 
expression in order of appearance. Returns the value of the expression immediately following the first value 
expression that matches. If no expression matches, returns the final DefaultReturnExpression if present, null 
otherwise. 

The types of all the return expressions must be compatible. For example, you can't mix numeric and text return 
value types. 

Example: 

Case("Shipped by", 1, 'FedEx', 2, 'UPS', 3, 'USES', 'Unknown') 

CaseRange {NumericExpressionInputy NumericExpressionIy ReturnExpressionIy NumericExpression2y 
ReturnExpression2[y ..., NumericExpressionNy ReturnExpressionN][yDefaultReturnExpression]) 

Takes 2N+1 or 2N+2 arguments: an expression followed by one or more numeric expression/retum expression 
pairs, with an optional final return expression. Finds the first numeric expression that is greater than the input 
expression and returns the value of the corresponding return expression. If no expression is greater, returns the 
final DefaultReturnExpression if present, null otherwise. 

The types of all the return expressions must be compatible. For example, you can't mix numeric and text return 
value types. 
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Examples: 

Case("Temperature", 60, 'too cold', 80, 'just right', 'too hot') 

CaseRange(CountAll("Shipping charge") % CountAll("Shipping charge", 'Total'), 2.0, 'Less 
than 2%', 5.0, '2% - 5%', 'More than 5%') 

CaseV^hen(BooleanExpression1 y ReturnExpressionI^ BooleanExpression2y ReturnExpression2[y,,,y 
BooleanExpressionNy ReturnExpressionN] [, DefaultReturnExpression]) 

Takes 2N or 2N+1 arguments: one or more pairs of Boolean expressions followed by return expressions, with an 
optional final return expression. Returns the expression immediately following the first tme Boolean expression. 
If no expression is tme, returns the final DefaultReturnExpression if present, null otherwise. This is the most 
flexible constmct. 

The types of all the return expressions must be compatible. For example, you can’t mix numeric and text return 
value types. 

Examples: 

CaseWhen("Shipped by" == 1, 'FedEx', "Shipped by" == 2, 'UPS', "Shipped by"== 3, 'USPS', 

'Unknown') 

Case("Temperature" <= 60, 'too cold', "Temperature" > 80, 'too hot', 'just right') 

Concatenate (TextExpression 1 [ , TextExpression2y ..., TextExpressionN]) 

Combines multiple text strings and/or fields into a single text field. Text strings are enclosed in single quotes; 
labels for fields or measures in Ad Hoc are enclosed in straight quotes. 

Examples: 

Concatenate ("Last Name", ' , ', "First Name") 

Concatenate("Product Category", ' , "Product Name") 

Conta\ns(TextExpression 1 , TextExpression2]) 

Boolean that returns tme if the first string contains the second, false otherwise. 

Example: 

Contains("Product Name", 'Soda') 

Co u n tAl I (Expression [, leve/') ] 

Returns the count of non-null items in a field or measure; note that CountAll always returns a non-negative 
integer. Level can be one of the following: Current (default), ColumnGroup, ColumnTotal, RowGroup, 
RowTotal, Total. See Levels in Aggregate Functions for more information. 

Example: 

CountAll ( "Transaction Amount", ' RowGroup ') — Counts the total number of non-null transactions in the 
specified group. 

CountDistinct(Expression[,leve/']) 

Returns the distinct count of non-null items in the input. Always returns a non-negative integer. Level can be 
one of the following: Current (default), ColumnGroup, ColumnTotal, RowGroup, RowTotal, Total. See Levels 
in Aggregate Functions for more information. 
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Example: 

CountDistinct ( "Customer Name", ' Total ') — Counts the number of distinct customers. 

Date ('Sfr/ngExpress/on') 

Casting hmction that takes a String expression and converts it to a Date data type. The String can be any 
expression that returns a supported string, including a field value or an attribute retrieved with the Attribute 
() function. The Date () function requires a String value formatted as 'yyyy-MM-dd'. Other Strings will return 
an error. 

Examples: 

Date(’2015-07-17') 

Date(Attribute('my_date_attribute')) 

Decimal('Sf r/ngExpress/on') 

Casting function that takes a String expression and converts it to a Decimal data type. The String can be any 
expression that returns a supported string, including a field value or an attribute retrieved with the Attribute 
0 function. The Decimal () function requires a String value in decimal format, for example, T23.45'. Other 
Strings will return an error. 

Example: 

Decimal ('1234.567') 

DayName (DateExpression) 

Given a date field, returns a text field with the name of the day of the week. 

Examples: 

DayName ("Open Date") — Displays the day of the week on which a store was opened. 

Mode (DayName ( "Open Date") , ' Total') — The day of the week on which the most stores were opened. 

DayNumber (DateExpression) 

Numeric field that returns the day of the month from a date field. 

Example: 

DayNumber ( "Open Date") — Displays the day of the month on which a store was opened. 

Elapsed Days (DateExpression^ DateExpression!) 

Calculates the number of days elapsed between two date fields that contain time values. 

Example: 

ElapsedDays ("Date shipped","Date required") 

ElapsedHours (DateTimeExpressionly DateTimeExpression!) 

Calculates the number of hours elapsed between two date fields that contain time values. 

Example: 

ElapsedHours ("Date shipped","Date required") 


144 


TIBCO Software Inc. 




Chapter 5 Working with the Ad Hoc Editor 


ElapsedMinutes (DateTimeExpressionI,DateTimeExpression2) 

Calculates the number of minutes elapsed between two date fields that contain time values. 
Example: 

ElapsedMinutes ("Date shipped","Date required") 

ElapsedMonths (DateTimeExpressionIyDateTimeExpressionZ) 

Calculates the number of months elapsed between two date fields that contain time values. 

Example: 

ElapsedMonths ("Date shipped","Date required") 

ElapsedQuarters (DateExpressionI^ DateExpression2) 

Calculates the number of quarters elapsed between two date fields. 

Example: 

ElapsedQuarters ("Date shipped","Date required") 

ElapsedSeconds (DateTimeExpressionlyDateTimeExpression2) 

Calculates the number of seconds elapsed between two date fields that contain time values. 

Example: 

ElapsedSeconds ("Date shipped","Date required") 

ElapsedSemis (DateExpression 1 , DateExpression2) 

Calculates the number of semi-years elapsed between two date fields. 

Example: 

ElapsedSemis ("Date shipped","Date required") 

ElapsedWeeks (DateExpressionIyDateExpression2) 

Calculates the number of weeks elapsed between two date fields that contain time values. 

Example: 

ElapsedWeeks ("Date shipped","Date required") 


This replaces the two-date custom field operation Date Difference > Weeks available in Ad Hoc 
views created in Server 5.5 or earlier. 


Elapsed Years (DateExpressionI jDateExpression2) 

Calculates the number of years between two date fields. 

Example: 

ElapsedYears ("Date shipped","Date required") 

EndsWith {TextExpression 1, TextExpression2] 

Boolean that returns tme if the first text input ends with the string specified in the second input; false otherwise. 
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Examples: 

EndsWith("Product Name", 's') 

IF (BooleanExpressioriy ExpressionWhenTrue[y ExpressionWhenFalse]) 

Given a Boolean field or calculation as the first argument, returns the second argument if tme; optionally returns 
the third argument if false. Returns null if the first argument is null. 

ExpressionWhenFalse must be of the same type as ExpressionWhenTrue. For example, if 
ExpressionWhenTrueis a date, ExpressionWhenFalse must be a date in the same format. If 
ExpressionWhenFalse is not set, then a false result returns a null value. 



You can create a BooleanExpression using the comparison operators(“==”, “<=”); 

any functions that return Boolean values (startswith, EndsWith, isNuii, Contains) and logical 
operators (and, or, not). 



(hen dates are used in comparisons or the IF function, they must be the same type, (date only, date/time, 
' time only). Make sure to use the correct modifier (d, ts, t) when using date constants in comparisons. 


Example: 


IF (Contains ("Product Name", 'Soda'), 'Yes', 'No') — Uses the Contains hinction to see whether the 
product name contains the string "Soda"; if it does, sets the field value to Yes. 

lnteger('Sf r/ngExpress/on') 

Casting function that takes a String expression and converts it to a Integer data type. The String can be any 
expression that returns a supported string, including a field value or an attribute retrieved with the Attribute 
0 function. The integer () function requires a String value that can be read as an integer, such as T23'. Other 
Strings will return an error. 

Examples: 

Integer('123' ) 

Integer(Attribute('my_integer_attribute')) 

\stiull(Expression) 

Boolean that returns tme if the field value is null; false otherwise. 

Example: 

IsNull("First Name") 

Length (TextExpression) 

Given a text string, returns its length. Null values return null. 

Example: 

Length("First Name") 

Max (NumericExpression \ DoteExpression[y'Level']) 

Returns the maximum value reached by the specified field or calculation. Level can be one of the following: 
Current (default), ColumnGroup, ColumnTotal, RowGroup, RowTotal, Total. See Levels in Aggregate 
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Functions for more information. 

Example: 

Max("Salary") 

Median (NumericExpression\ DateExpression[y'Level']) 

For an odd number of values, returns the middle value after all values are listed in order. For an even number of 
values, returns the average of the middle two values. For example, if a field has only five instances, with values 
{1,1,3,10,20}, the median is 3. Level can be one of the following: Current (default), ColumnGroup, 
ColumnTotal, RowGroup, RowTotal, Total. See Levels in Aggregate Functions for more information. 

Example: 

Median("Salary") 

Mid (7 extExpression,Integer 1 , Integer!) 

Given a text string, returns the substring starting at Integer 1 with length Integer2. 

Example: 

Mid ("Phone", 1, 3) — Given an American phone number starting with a 3-digit area code, extracts the area 
code. 

Min (NumericExpression \ DateExpression[y'Level']) 

Returns the minimum value reached by the specified field or calculation based on an optional level. Level can 
be one of the following: Current (default), ColumnGroup, GolumnTotal, RowGroup, RowTotal, Total. See 

Levels in Aggregate Functions for more information. 

Example: 

Min("Salary") 

Mode (Expression[y'Level']) 

Returns the most frequent value reached by the specified input, based on an optional level. For example, if a 
field has only five instances with values {1,2,2,4,5}, the mode is 2. Level can be one of the following: 

Gurrent (default), ColumnGroup, GolumnTotal, RowGroup, RowTotal, Total. See Levels in Aggregate 
Functions for more information. 

Example: 

Mode (DayName ("Order Date", RowGroup) ) — For each row group, returns the day of the week on which 
the most orders were placed. 

MonthName (DateExpression) 

Returns a text field with the name of the month. 

Example: 

MonthName ("Order Date" ) 

MonthNumber (DateExpression) 

Returns the number of the month, with January = 1 and December = 12. Null values return null. 

Example: 
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MonthNumber ("Order Date") 


PercentOf (NumericExpression[,'Level']) 

Returns the value as a percent of total for the specified level. Null values are ignored. Note that possible values 
for Level are ColumnGroup, ColumnTotal, RowGroup, RowTotal, Total (default). See Levels in Aggregate 
Functions for more information. 



PercentOf (NumericExpression, Total) replaces the custom field calculation Percent of Total 
Group available in Ad Hoc views created in Server 5.5 or earlier. 


07 


Calculated fields using the PercentOf function should not be used as filters; if PercentOf is used as 
a filter, then the total percent may not be 100. 


Example: 

PercentOf("") 

Range (NumericExpression[y'Level']) 

The difference between the largest and smallest values of the given input. 

Example: 

Range("Salary",'GolumnGroup') 

Rank (NumericExpression) 

Returns the position of each value relative to the other values after all the values are listed in order. For 
example, the top ten in sales are the top ten in rank. Null values are ignored. 

Example: 

Rank("Store Sales") 

Round (NumericExpression[Jnteser]) 

Rounds a number to a specified number of digits; default is zero (0) digits. Decimal values greater than 0.5 are 
rounded to the next largest whole number, and values less than 0.5 are rounded down. 

Example: 

Round("Sales") 

StartsWith (Text Express! on 1 , Text Expression!] 

Boolean that returns tme if the first text input starts with the string specified in the second input; false 
otherwise. 

Examples: 

StartsWith("Product Name", 'Q') 

StdevP (NumericExpression[,'Level ']) 

Standard deviation based on the entire population, taken over the values at the specified (optional) level. Null 
values are excluded. Level can be one of the following: Current (default), ColumnGroup, ColumnTotal, 
RowGroup, RowTotal, Total. See Levels in Aggregate Functions for more information. 
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Examples: 

StdevP("Sales",'RowTotal') 

StdevS (NumericExpression[y'Level']) 

Standard deviation based on a sample, taken over the values at the specified level. Null values are excluded. 
Level can be one of the following: Current (default), ColumnGroup, ColumnTotal, RowGroup, RowTotal, 

Total. See Levels in Aggregate Functions for more information. 

Example: 

StdevS("Sales",'RowTotal') 

Sum (NumencExpression[y'Level']) 

The sum of all values in the range. Null values are 
(default), ColumnGroup, ColumnTotal, RowGroup, 
more information. 

Examples: 

Sum("Sales",'RowGroup') 

Time('Sf r/ngExpress/on') 

Casting hmction that takes a String expression in the format ’HH:mm:ss.SSS' and converts it to a Time data type. 
The String can be any expression that returns a valid String, including a field value or an attribute retrieved 
with the Attribute () function. 

Examples: 

Time('17:12:33:147') 

Time(Attribute('my_time_attribute')) 

Timestamp ('Sfr/ngExpress/on') 

Casting hmction that takes a String expression in the format 'yyyy-MM-dd HH:mm:ss.SSS' and converts it to a 
Timestamp data type. The String can be any expression that returns a valid String, including a field value or an 
attribute retrieved with the Attribute () function. 

Examples: 

Timestamp('2015-07-17 17:12:33:147') 

Timestamp(Attribute('my_timestamp_attribute')) 

Today (Integer) 

Calculates the date that is the specified number of days from the current system date. 

Examples: 

Today ( 0) — The current system date. 

Today (1) — The day after the current system date. 

Today (-1) — The day before the current system date. 


excluded. Level can be one of the following: Current 

RowTotal, Total. See Levels in Aggregate Functions for 
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WeightedAverage (NumericExpressionl.NumericExpressionl,'Level') 

Returns the weighted average for the first input weighted with respect to the second input, calculated at an 
optional level. Null values are excluded. Level can be one of the following: Current (default), ColumnGroup, 
ColumnTotal, RowGroup, RowTotal, Total. See Levels in Aggregate Functions for more information. 

Examples: 

WeightedAverage ("Price", "Units", ' Gurrent ') — The extended price based on the number of units. 

WeightedAverage ("Price", "Units", 'RowGroup') —The sum of the extended price for all units in the 
row group. 

Year (DateExpression) 

Given a date field, returns the year. 

Examples: 

Year("Order Date" ) 


.6.5 Calculated Field Syntax 

This section describes the syntax required when creating calculated fields in Ad Hoc views. See Calculated 
Field Reference for more information. 

Use the following syntax for inputs: 

• To reference a text string, use single quotes (') — ' Text string '. 

• To reference a field label, use double quotes (") — "Ad Hoc Label'\ 

• To reference date constants, indicate the date type as part of the syntax, as listed below: 

• To reference a date without time data (for example: yyyy-dd-mm), use d followed by single quotes (') 

— d'2014-06-10' 

• To reference a date with day and time data (for example: yyyy-dd-mm hh:mm:ss), use ts followed by 
single quotes (’) — ts' 2014-06-10 01:30:00' .If you use ts and enter the date information only, the 
time is automatically set to 00:00:00. 

• To reference a date with time data only (hh:mm:ss), use t followed by single quotes (') — 

t' 01:30:00' 

• To reference a date field label, use double quotes (") — "Ad Hoc Date Field LaheTt 



The following are reserved words and cannot be used as field names: AND, And, and, IN, In, in, NOT, 
Not, not, OR, Or, or. Names containing these strings, such as "Not Available", can be used. 


When dates are used in comparisons or the IF function, they must be the same type, (date only, date/time, 
or time only). Make sure to use the correct modifier (d, ts, t) when using date constants in comparisons. 


In the fonction descriptions for calculated fields in Calculated Field Reference, the argument name describes 
the type of input the function accepts. For more information about input types, see TIBCO JasperReports Server 
Data Management Using Domains: 

• BooleanExpression — Any expression that takes on Boolean values, including the label of a Boolean 
field or measure, a Boolean calculation, or a Boolean value. 
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You can create a BooleanExpression using the following: comparison operators (==, !=, >, >=, <, <=, in); 
functions that return Boolean values (StartsWith, EndsWith, IsNull, Contains) and logical functions (AND, 
OR, NOT). 


DateExpression — Any type of date or timestamp values, including the label of a date field or measure, 
or a calculation that returns dates. 

DateTimeExpression — Date expressions that contain time values, including the label of a date field or 
measure, or a calculation that returns dates. These values are also known as timestamp values. 

Expression — Any valid date, date-time, numeric, or string expression. 

NumericExpression — Numeric values, including the label of a numeric field or measure, or a calculation 
that returns numbers. 

TextExpression — Text values, including the label of a text field or measure, or a text string. 

Level — For aggregate hmctions, specifies the set of values used to compute the calculation. Possible 
values include Current (not available for PercentOQ, ColumnGroup, ColumnTotal, RowGroup, RowTotal, 
Total. See Levels in Aggregate Functions for more information. 


.6.6 Operators in Ad Hoc Views 

Ad Hoc views support the following operators in calculated fields. Operators are evaluated in the order they are 
shown in the table: 


Operator 

Syntax 

Description 

multiply, divide 

i ^ j / k 

Arithmetic operators for numeric types only. 

percent 

i % j 

Calculates i as a percent of j; numeric types only. 

add, subtract 

i + j - k 

Arithmetic operators for numeric types only. 

equal 

i == j 

Comparison operators for string, numeric, and 
date types. 

not equal 

i != j 

less than 

i < j 

Comparison operators for numeric and date types 
only. 

less than or equal 

i <= j 

greater than 

i > j 

greater than or 
equal 

i >= j 

IN set 

i IN ('applesG'oranges') 

Sets can be of any type. 

IN range 

i IN (j :k) 

Ranges must be numeric or date types. 
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Operator 

Syntax 

Description 

NOT 

NOT( i ) 

Boolean operators. Parentheses are required for 

NOT. 

AND 

i AND j AND k 

OR 

i OR j OR k 

parentheses 

0 

Used for grouping. 


When dates are used in comparisons or IF functions, they must be the same type, (date only, date/time, or 
time only). Make sure to use the correct modifier (d, ts, t) when using date constants in comparisons. 



The following reserved words cannot be used as field names: AND, And, and, IN, In, in, NOT, Not, not, 
OR, Or, or. Names containing these strings, such as "Not Available", can be used. 


.6.7 Aggregate Functions 

Aggregate functions in calculated fields perform calculations based on groups of rows, rather than on single 
rows. For example, it doesn't make sense to use Sum or Average on a single value; instead, you want to take the 
sum or average over a row or column group or over the total set. In many cases, aggregate hmctions in the Ad 
Hoc Editor are analogous to SQL functions that can be used with the GROUP BY clause in a SELECT 
statement. 

The aggregate functions are as follows: 


Average 

Median 

Range 

W eightedA verage 

CountAll 

Min 

StdDevP 


CountDistinct 

Mode 

StdDevS 


Max 

Percent Of 

Sum 



Because aggregate functions already operate on groups, their use is restricted in the following ways: 

• You can use aggregate functions only in calculated measures; aggregates should not be used to create non¬ 
measure fields. 

• You cannot add an aggregate fianction to a group. 

• You should not use an aggregate function as a filter. 

• Only Aggregate Formula, Custom, or None are supported as summary calculations for aggregate fiinctions. 
Custom appears in the Change Summary right-click menu only if you have defined a custom function in 

the Create Calculated Field dialog box. 

5.6.7.1 Levels in Aggregate Functions 

Many aggregate functions accept an optional level to specify the grouping of the aggregate. A level used in an 
aggregate, must be enclosed in straight quotes ('), for example, ' RowGroup ' . 

The available levels are as follows: 

• Current (default) — use the current value when at a looking at detail rows in a table view. 

• RowGroup — use the parent values from a row location. 
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• RowTotal — use the grand total value from a row location. 

• ColumnGroup — use the parent values from a column location. 

• ColumnTotal — use the grand total value from a column location. 

• Total — use the grand total value from a cross tab and the RowTotal from a Table. 

The following example shows how RowGroup works with the PercentOfO function. 

Setting up the Ad Hoc view: 

The examples in this section uses the Ad Hoc view created in Creating a Calculated Field. The initial view for 
these examples can be set up as follows: 

1. Select Crosstab from the Visualization Selector. 

2. Add Store Sales 2013 and Low Fat to the Columns entry bar. 

3. Add Country and Store Type to the Rows Entry Bar. 

4. To make the example clearer, the data has been restricted. To do this, create three filters: 

a. Expand Regions in the Fields Picker, right-click on Country, and select Create Filter. In the Filters 
pane, set the filter to is one of then select Canada and USA. 

b. Create a filter for Store Sales 2013. In the Filters pane, set the filter to is greater than, and enter 19.70. 

c. Right-click on Store Type and select Create Filter. In the Filters pane, set the filter to is one of then 
select Deluxe Supermarket, Gourmet Supermarket, and Mid-Size Grocery. 



o 

<1. 

h. 


Columrs 

Rows 


1 

Store Sales 2013 m 

1 

LowFai « 






Click to add a title 



S Measures 

E Store Sales 2013 


Low Fat 

false 

true 

Totals 

E Country 

Store Type 




□ Canada 

Deluxe Supermarket 

102.17 

19.90 

122.07 


Mid-Size Grocery 


19.75 

19.75 


Totals 

102.17 

39.65 

141.82 

□ USA 

Deluxe Supermarket 

220.56 

40.75 

261.31 


Gourmet Supermarket 

138.80 


138.80 


Mid-Size Grocery 

19.75 


19.75 


Totals 

379.11 

40.75 

419.86 

Totals 

Totalis 

4ai.28 

80.40 

561.68 


Sample Data ^ | Filters 

A.Country 
Available: 3 


is one of t 
S elected: 2 


X Canada 
X USA 


B.Store Sales 2013 


19.70 


C. Store Type 
Available: S 


15 one of T 
Selected: 3 


X Deluxe Superm a licet 
X Gourmet Supermarket 
X Mid-Size Grocery 


> Cu sto m Fi Lte r Express I on 


Figure 5-20 Base Example for Levels 

RowGroup example: 

To create the layout for this example: 
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1. Click * at the top right of the Measures section of the Data Source Selection panel and select Create 
Calculated Measure... from the context menu. 

2. In the Create Calculated Measure dialog box, enter Percent of Row Group for the name, and enter 
PercentOf ("Store Sales 2013", ' RowGroup ') in the Formula entiy box. Then click Create Measure. 

3. Drag the measure you just created to the Columns bar, between Store Sales 2013 and Low Fat. 

The crosstab appears as shown in the following figure. 



El Measures 

□ Store Sales 2013 

□ Percent of Row Group 


Low Fat 

false 

true 

Totals 

false 

true 

Totals 

El Country 

Store Type 







□ Canada 

Deluxe Supermarket 

102.17 

19.90 

122.07 

100.00 

50.19 

36.07 


Mid-Size Grocery 


19.75 

19.75 


49.81 

13.93 


Totals 

102.17 

39.65 

141.82 

21.23 

49.32 

25.25 

□ USA 

Deluxe Supermarket 

220.56 

40.75 

261.31 

58.18 

100.00 

62.24 


Gourmet Supermarket 

138.80 


138.80 

36.61 


33.06 


Mid-Size Grocery 

19.75 


19.75 

5.21 


4.70 


Totals 

379.11 

40.75 

419,86 

78.77 

50.68 

74.75 

Totals 

Totals 

4ai.28 

30.40 

561.68 

100.00 

100.00 

100.00 


Figure 5-21 Example for RowGroup 

Look at the Low Fat values for "false" in the Canada group. The only non-null value under Store Sales 2013 is 
in the first row, for Deluxe Supermarket. This value, 102.17, is 100% of the row group total of 102.17 on the 
third line of the crosstab. This percentage is shown in the "false" subcolumn of the Percent of Row Group 
column. 

Compare this to the "tme" entry under Store Sales for the same (first) row. There, the value is 19.90, and the row 
group total is 39.65. The corresponding percentage shown in the "tme" subcolumn of Percent of Row Group is 
50.19%. 


5.6.8 Summary Calculations 

Summaiy calculations are aggregate functions used for sub-totals and totals. Summaiy calculations can be set in 

the Domain Designer or in the Ad Hoc view. 

• In Ad Hoc table views, each field can display a single summary calculation. The summaiy calculation is 
automatically applied to all groups in the table. Summaries appear at the bottom of each group, as well as at 
the bottom of the view. When a new group is added, it includes a summaiy for each column. 

• In crosstabs, each measure displays a summarized value. Summaries determine the values of the Totals at the 
intersection of each row and column. 

• In charts, the type of chart determines whether measures are summarized. If summaries are used, they 
determine the size or location of the graphical elements that represent your data. 



For dual pie charts, the summary function for the field needs to be Sum or CountAII. Dual pie charts 
with other summary functions may give unexpected results. 


In general, you can change the summaiy calculation of any measure. By default, JasperReports Server 
summarizes fields of each datatype as shown in the following table. 
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Table 5-3 Default Summary Functions in Calculated Fields 


Datatype 

Default Summary 
Calculation 

Description 

Numeric 

Sum 

Displays the sum of all values in the set. 

Date 

CountAII 

Displays the total number of values in the set. 

String 

CountAII 

Displays the number of values in the set. 

Boolean 

CountAII 

Displays the number of values in the set. 

Aggregate 

Aggregate Formula 

For a calculated field that uses an aggregate function, uses 
the same aggregate formula as the summary. 

Combined 

None 

For a calculated field that combines an aggregate function 
with a non-aggregate function, the summary calculation is 
null. 


Select from the following options to set a measure’s summary tlinction in any type of view. 


Function 

Meaning 

Available for.... 

Aggregate Formula 

For a calculation that uses an aggregate function, 
uses the same aggregate formula as the 
summary. 

Aggregate 

Average 

Displays the average of all values in the set. 

Numeric 

CountAII 

Displays the number of rows in the set. 

Boolean, Date, Numeric, and 

String 

CountDistinct 

Displays the number of unique values in the set. 

Boolean, Date, Numeric, and 

String 

Custom 

Allows you to enter an aggregate calculation for 
the summary. Only available for calculated fields 
and measures in the Ad Hoc Editor; not available 
for Domains. 

Aggregate, Date, Numeric 

Maximum 

Displays the highest value in the set. 

Date, Numeric 

Median 

Displays the median value of the set. 

Date, Numeric 

Minimum 

Displays the lowest value in the set. 

Date, Numeric 

Mode 

Displays the value that occurs most frequently in 
the set. 

Boolean, Date, Numeric, and 

String 
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Function 

Meaning 

Available for.... 

None 

The aggregate function is null; no summary 
function is displayed. 

Aggregate, Boolean, Date, 

Numeric, and String 

Range 

Displays the difference between the minimum 
and maximum values of the set. 

Numeric 

RangeDays 

Displays the difference in days between the 
minimum and maximum values of the set. 

Date 

RangeHours 

Displays the difference in hours between the 
minimum and maximum values of the set. 

DateTime 

Range Minutes 

Displays the difference in minutes between the 
minimum and maximum values of the set. 

DateTime 

RangeMonths 

Displays the difference in months between the 
minimum and maximum values of the set. 

Date 

RangeQuarters 

Displays the difference in quarters between the 
minimum and maximum values of the set. 

Date 

RangeSemis 

Displays the difference in semi-annual periods 
between the minimum and maximum values of 

the set. 

Date 

RangeWeeks 

Displays the difference in weeks between the 
minimum and maximum values of the set 

Date 

RangeYears 

Displays the difference in years between the 
minimum and maximum values of the set. 

Date 

Standard Deviation 

P 

Displays the standard deviation for the 
population of the set. 

Numeric 

Standard Deviation 

S 

Displays the standard deviation on a sample for 
the set. 

Numeric 

Sum 

Displays the grand total for the set. 

Numeric 

Weighted Average 

Displays the weighted average for the set, based 
on a second numeric field or expression. Only 
available for calculated fields and measures in 

the Ad Hoc Editor; not available for Domains. 

Numeric 


Note the following about summaries: 

• If you select a summary calculation other than the default, that calculation is shown in parentheses after the 
field name in the fields picker. 
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• In Ad Hoc views, you see special behavior when you create a calculated field or measure with the 
following type of summaiy calculation: 

• If you create a Custom summary calculation for a field or measure, Custom is available on the 
Change Summary Calculation menu for that field. It is not available otherwise. 

• If you create a WeightedAverage summaiy calculation for a field or measure. Weighted Average is 
available on the Change Summary Calculation menu for that field. It is not available otherwise. 

• You can remove summaries by setting the summaiy function to None. 

• Only AggregateFormula, Custom, or None are supported as summaiy calculations for aggregate functions. 
Custom only appears in the Change Summary right-click menu if you have defined a custom function in 

the Create Calculated Field dialog box. 


.7 Using Filters and Input Controls 

JRXML Topics, Domains, and OLAP connections use different mechanisms for screening the data they return: 

• JRXML Topics can contain Parametrized queries. The parameters can be mapped to input controls that 
allow users to select the data they want to include. 

• Domains (and Domain Topics) can be filtered by selecting fields in the Domain and specifying comparison 
values. The filters can be configured for users to select the data to include. 

• Within the Domain design, filters based on conditions can also be defined; these filters are not displayed in 
the report viewer when the report mns. 

• OLAP connections rely on XML schemas to filter the data in an underlying transactional database. Input 
controls are never generated directly from the OLAP schema. 

You can define filters in the Ad Hoc Editor regardless of whether you are working with data from a Domain, 
Topic, or OLAP connection. Such filters can be helpful in improving the view's initial performance by reducing 
the amount of data the view returns by default. For more information, see ‘‘Input Controls and Filters 
Availability” on page 163. To prevent users from seeing the full dataset, you can also use input controls in a 
JRXML Topic or filters defined in the Domain design, which can be hidden from end users. 

If you want to return different data to different users of the same view, define data-level security based on a user 
roles and profile attributes. This is available for reports based on a Domain, Domain Topic, or OLAP client 
connection. For more information, refer to the TIBCO Jaspersoft OLAP User Guide. 

Input controls and filters interact seamlessly. For example, you can create filters in an Ad Hoc view that gets 
data from a JRXML Topic that includes input controls. 

The server refreshes the editor against both the filters and the input controls. Because some combinations 
of input controls and filters don’t return data, this can result in an empty view. 


If the result set is empty, check for an incompatible combination of filters and input controls, such as a 
standard filter (set to Mexico against a Country field) and a Keep Only filter (set to Canada against a 
Country field), or an incorrectly-defined advanced filter expression (data must meet all criteria in multiple 
filters, rather than meeting criteria in a subset of those filters). See “Custom Filtering” on page 159 for 
information on advanced filter expressions. 


In rare cases, filters can conflict with view parameters, and you’ll need to rename the field causing the conflict 
by editing the JRXML file. Refer to the TIBCO Jaspersoft Studio User Guide for more information about 
editing JRXML files. 

For more information about: 
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• JRXML Topics and input controls, see ^‘Adding Input Controls” on page 190. 

• Domain Topic filters, see ^‘Creating Topics from Domains” on page 171. 

• Localizing input control prompts and lists of values, see ‘‘Localizing Reports” on page 204. 


.7.1 Using Filters 

Filters can be defined at three levels: 

• In the Domain Designer. 

• When creating a view from a Domain (with the Data Chooser). 

• In the Ad Hoc Editor (even when the view is based on a JRXML Topic or OLAP connection). 

In this section, we discuss how to define filters in the Ad Hoc Editor. For information on defining filters in the 
Domain Designer, see TIBCO JasperReports Server Data Management Using Domains. For information on 
defining filters in the Data Chooser, see “The Pre-filters Page” on page 167. 

In addition, you can control how and what filters are applied to a field or fields by using custom expressions. 
For more information, see “Custom Filtering” on page 159. 

To create a filter in the Ad Hoc Editor: 

1. Right-click a field in the Data Source Selection panel and select Create Filter. A new filter appears in 
the Filters panel. If the Filters panel was hidden, it appears when you create a new filter. 


If the results are empty and you don’t understand why, check for an incompatible combination of filters and 
input controls. Clickto compare input controls with the filters in the Filters panel. 


2. Use the fields in the filter to change its value. Depending on the datatype of the field you selected, the 
filter maybe multi-select, single-select, or text input. 

3. Click and select Minimize All Filters or Maximize All Filters to toggle expansion of the items in the 
filter. 

4. Click and select Remove All Filters to remove the filters. 

5. Click ▼ to hide the filter’s details. Click ► to display them again. 

6. Click the Select All check box (if it appears in the Filters panel) to select all values currently available in 
the dataset. The Select All check box does not appear in the Filters panel for numbers and dates. 

Note that the Select All check box doesn’t guarantee that all values are selected every time the report mns. 
Instead, the check box is a shortcut to help you quickly select all the values currently available in the 
dataset. To ensure that all values appear in the view whenever it is edited or a report is mn, remove the 
filter entirely. On the panel, you can also create a filter from the right-click context menu of a column in a 
table. On the Chart tab, you must right-click the field in the Data Source Selection panel. 

When you change a filter, the server uses the filter's new value to determine what data to display. If you change 
only the operator in a filter, you must deselect the value in that filter, then reselect it to apply the updated filter. 

For filters with multiple values, you do not need to reselect all values. After changing the operator, use Ctrl- 
click to deselect just one of the values, then Ctrl-click to reselect that value. 

5.7.1.1 Relative Dates 

You can filter information in your view based on a date range relative to the current system date. You can 
accomplish this using date-based filters, and entering a text expression describing the relative date or date span 
you want to display, using the format <Keyword>+/-<Number> where: 
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• Keyword indicates the time span you want to use. Options include: DAY, WEEK, MONTH, QUARTER, 
SEMI, and YEAR. An option used by itself (without +/-<Number>) gives the current value for that option. 

• + or - indicates whether the time span occurs before or after the chosen date. 

• Number indicates the number of the above-mentioned time spans you want to include in the filter. 

For example, if you want to look at all Sales for the prior week, your expression would be: WEEK-1. 

To create a relative date filter: 

1. Following the instmctions in “Using Filters” on page 158, create a filter based on a date field. The filter 
appears in the Filters panel. 

2. In the filter’s first text entiy box, enter an expression describing the relative date or date span you want to 
display. 

3. In the filter’s second text entiy box, enter the date you want to base your filter on. 

For instance, if you want to display all the sales numbers for one month before the current date, enter 
MONTH-1 in the first text entiy box, and enter today's date in the second box. 



When you right-click a group member in a crosstab and select Keep Only or Exclude, you create complex 
filters. When you create a filter against an inner group, the filter that appears may be created as a complex 
filter. You can't edit a complex filter, but you can remove it. Complex filters also appear in the Ad Hoc 
Editor if a Data Chooser filter was created and locked. 


5.7.1.2 Custom Filtering 

When you create multiple filters they are, by default, connected with an implicit AND operator. That is, the 
data displayed in your table, chart, or crosstab is what remains after all your filters are applied. 

However, with the custom filter functionality, you can exercise greater control over the displayed data by 
applying a custom expression that includes more complex, nested AND, OR, and NOT operators, as well as by 
applying multiple filters to a single field. 


Custom filters are not available for Ad Hoc views created from OLAP connections. 


Custom filters are useful in a number of situations, including: 

• When using the AND operator isn’t sufficient. Consider an international company that wants to view 
data for stores located on the Pacific Rim; they may create a custom expression with the following criteria: 

• Country is USA 
AND 

• State is California OR Washington OR Oregon OR Hawaii OR Alaska. 

OR 

• Countiy is Japan OR Indonesia 

Using the AND operator for all of these criteria returns an empty view, as no store is located in all of those 
areas. 

• When you need to eliminate some results in a field. For example, if your food and beverage 
distribution company wants to view sales for all drinks except for high-price items, you might include the 
following criteria in a custom expression: 

• Product Group is Beverages 
NOT 

• Price is greater than 39.99 
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This filter displays all items in the Beverage Product Group, but filters out those with prices over $39.99 

These are only two scenarios where custom filters can hone your results and make your view more precise. 
There are, of course, many other situations where they can be applied. 

In this section, we take you through these tasks: 

• Creating a custom expression 

• Editing a custom expression 

• Removing a custom expression 

• Applying multiple filters to a single field 


Custom filters are applied to views, but filter details don’t appear on previews or on the report generated 
from that view. 


To create and apply a custom filter: 

1. Create two or more filters for your data, as described in “Using Filters” on page 158. These can be standard 
field-based filters, or Keep Only and Exclude filters. 

Note that as you create the filters for use in a custom expression, you may find that the data in your view 
disappears, since most (if not all) of the data won’t meet all of the filter criteria. When you create your 
custom expression and change some of the ANDs to ORs and NOTs, data reappears in the panel. 

2. At the bottom of the Filters panel, expand the Custom Filter Expression section. 

3. In the text entry box, enter a filter expression using the letter designations, and including the following 
operators: 

• AND narrows your results and includes only fields that meet the criteria of both filters before and after 
the operator. 

• OR broadens your results and includes fields that meet the criteria of either filter before or after the 
operator. 

• NOT excludes results that match the criteria. 

• Parentheses combines multiple filters into a single item in the expression. 



Filter letter designations are case sensitive, and must be UPPERCASE. 


4. Click Apply. Your view is updated to reflect the newly-applied filter criteria. 

After creating a custom filter, you may want to add another filter to the expression or remove one already 
included in the expression. 



If the simple filter you want to delete is part of a custom filter, you must first remove it from the custom 
filter expression; otherwise deleting the filter deletes the custom filter expression. 


To add a new filter to an existing custom expression: 

1. If necessaiy, create the new filter in the Filter panel. 

2. In the Custom Filter Expression section, click inside the text entry box to edit the expression. 

3. Add the new filter to the expression. 

4. Click Apply to apply the new filter criteria. 

To remove a filter from a custom expression: 

1. Expand the Custom Filter Expression section. 
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2. In the text entiy box, remove the unwanted filter from the expression and adjust the expression as needed. 

3. Click Apply to apply the new filter criteria. 

When working with custom expressions, you may decide to delete an expression and create a new one. 

To remove a custom expression from a view: 

1. Expand the Custom Filter Expression section. 

2. Clear the expression from the text entry box. 

3. Click Apply. The expression is removed, leaving the remaining filters intact. 

When you refine your custom expression, you may also want to delete unused filters from the Filters panel. 

• If the filter you want to remove isn’t part of the custom filter, hover your mouse over in the filter’s title 
bar and select Remove Filter. 

• If you want to remove all existing filters, including the custom expression, hover your mouse over in 
the upper right comer of the Filters panhandle and select Remove All Filters. 

You can apply multiple simple filters to a single field, if needed, to further refine your custom filter results. For 
example, a user may want to view the data in the Shipping Cost field, but only when it meets certain criteria 
combinations: 

• When shipping costs to French cities with postal codes that begin with the number 5 are under five Euros 

• When shipping costs to German cities with postal codes that begin with the number 1 are under five Euros 


You can recreate the scenario below using the demo for adhoc topic. 


In the following example a user has a table including the following columns: 

• Countiy 

• Postal Code 

• Shipping Charge 

To analyze the specific shipping costs described above, the user creates the following (simple) filters - including 
two filters each for the Countiy and Postal code fields: 

• A. Countiy equals France 

• B. Postal code starts with 5 

• C. Country equals Germany 

• D. Postal code starts with 1 

• E. Shipping Charge is less than 5 

Then, to display only the information she needs, she creates the following custom expression: 

• ((A and B) or (C and D)) and E 

This translates to: 

• ((FRANCE and POSTAE CODES THAT START WITH 5) or (GERMANY and POSTAL CODES THAT 
START WITH 1)) and SHIPPING CHARGES LESS THAN 5 EUROS. 

.7.2 Using Input Controls 

In the Ad Hoc Editor, you can display the input controls defined in the Topic as visible to users. You can 
accept the controls’ default values or enter other values. The Ad Hoc Editor indicates that the view has input 
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controls by displaying H as active on the tool bar. Click this icon to select new values or to save values as the 
new defaults for this view. 

There are two types of input controls: Single select and multi-select. The input control type is determined by the 
operator you use. In turn, the available operators are determined by the field type (date, text, numeric, or 
boolean) you use as a filter. 

Single select controls present a calendar or drop-down list of values, from which you can choose a single value. 
To create this type of input control select one of the following operators: 

• equals 

• is not equal to 

• is greater than 

• is less than 

• is greater or equal to 

• is less or equal to 

• contains 

• does not contain 

• starts with 

• does not start with 

• ends with 

• does not end with 

• is before 

• is after 

• is on or before 

• is on or after 

Multi-select controls display a calendar or drop-down list of values, from which you can choose multiple 
values. You can click to select individual values or shift-click to select multiple sequential values. You can also 

search for values, ^ select all available values, ^ deselect all available values, or invert the selection. A 
Selected tab shows only items that are selected and allows you to delete them. To create this type of input 
control select one of the following operators: 

• is one of 

• is not one of 

• is between 

• is not between 


To add an input control to the view using a filter: 

1. Create a new filter or use an existing one in the Filters panel. 

2. In the Filters panel, click the operator drop-down menu in the filter’s title bar. 

3. Select an operator from the drop-down. The operator you select determines whether the input control is 
single-select or multi-select. 

4. Click Apply. The filter appears as an input control when the view is used to mn the report. 

P 

5. Place your cursor over , select Save Ad Hoc View as.... 

6. Name the view, select a location, and click Save. 

7. On the tool bar, click S . 
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Only the input controls defined in the topic appear here. Again, if no input controls were defined in the 
topic, the button appears inactive. You can create a report and open it in the report viewer to see a filter 
listed as an input control. 

To edit the values for a view’s input controls: 

1. On the tool bar, click . A window listing the input controls defined in the Topic appears. 



The Parametrized Report Topic already includes three input controls created when the report was 
uploaded: Country, RequestDate, and Orderld. 


2. Select new values. For example, select USA from the Country drop-down. 

3. To change default values of input controls, select the check box. Set these values as defaults when 
saving your view. The selected values become the default values when you save the view. 

4. Click OK. The Ad Hoc view shows USA data. 


.7.3 Input Controls and Filters Availability 

Input controls and filters can appear in the Editor and when a report mns: 

• Input controls can be set to be visible or invisible when you edit a view: 

• Input controls set to Always prompt are displayed in the editor and always appear before the report is 
mn. 

• Input controls that aren’t set to Always prompt are always hidden in the editor and hidden when the 
report is mn. 

• Filters defined in the Domain design are always hidden in the editor and when the report is mn. 

• Filters created in the Data Chooser can be locked or unlocked: 

• Filters that are unlocked display filter information in the editor and are available from the Options 
button when the report is mn. 

• Filters that are locked display input controls in the editor when you click to see the view in 
display mode but are not available from the Options button when the report is mn. Users can remove 
the filter while in the editor, allowing them to see all the data unfiltered when the report is mn. 

• You can’t change whether the filter is displayed after the report is created. 

• Filters defined in the editor are always available in the Filters panel of the editor and from the Options 
button when the report is mn. 

When setting up input controls for a huge view that takes a long time to mn, consider setting the view to 
Always prompt. Before a report is mn, the report viewer prompts you to provide the input options, preventing 
the report from mnning with the default input options. 

Filters that are unlocked are available. When input controls or filters don’t appear in the report viewer, click the 
Options button to view them. You can learn more about how filters and input controls interact in the editor by 
walking through the data exploration tutorial with the Filters panel open. 

To set an input control to always prompt: 

1. Locate a Topic, such as the Parametrized Report Topic, in the repository and click Edit. 

2. On the Controls & Resources page of the JasperReport wizard, under Input Control Options, select Always 
prompt: 


TIBCO Software Inc. 


163 




TIBCO JasperReports Server User Guide 


To 

1 . 

2 . 

3 . 


To 

1 . 

2 . 

3. 

4. 

5. 

6 . 

7. 

8 . 
9. 


determine whether an input control is visible: 

Locate a Topic, such as the Parametrized Report Topic, in the repository and click Edit. 

On the Controls & Resources page, click the name of an input control, such as Country. 

On the Locate Input Control page, click Next. 

At the bottom of the Create Input Control page, if the Visible check box is selected, the input control 
appears on the report when it mns. For more information, see “Adding Input Controls” on page 190. 


If you don’t provide a default value forthe input control, users are prompted to selecta value when 
they create a view based on the Topic. 


lock a filter: 

Click Create > Ad Hoc View. 

In the Select Data wizard, click and browse to Domains to create a new view based on a Domain. 
Click Choose Data. 

In Fields, move tables and fields from Source to Selected Fields. 

Click Pre-filters. 

Double-click a field in the Fields panel. 

In the Filters panel, define a filter as described in “The Pre-filters Page” on page 167. 

Check the Locked check box, and click OK. 

Click Table to open the Ad Hoc Editor. 

In the Filters panel, the name of the filter and a note about the lock appears under the heading Locked. 


.8 Creating a View from a Domain 

Like Topics and OLAP connections, administrators and data analysts create Domains for reuse to simplify access 
to data during view design. Domains give view makers more flexibility than Topics in choosing fields from the 
database and allow filtering of the data before it is included in a view and the subsequent report. 

A view based on a Domain can prompt the user for input that determines what data is presented. For example, if 
a Domain includes all sales data for a company, the view can present detailed information grouped by postal 
code and prompt the user to select the geographic area, such as a US state. The view displays only the pertinent 
information. 

For a more complete description of how to create Domains, see TIBCO JasperReports Server Data Management 
Using Domains. 

To begin create a basic view from a Domain: 

1. On the Home page, click Create > Ad Hoc View. The Select Data wizard opens. 

2. Click and navigate to Domains. A description of the selected Domain appears at the bottom of the 
Domains tab. 
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Select Data 


root 


Organizations 
H Organization 

► Ad Hoc Components 

► iH Analysis Components 
▼ H Domains 


^ Simple Domain 


^ Supermart Domain 
^ Virtual DS Domain 
Performance 


Public 


simple example of Domain 




choose Data... 

Cance[ 



Figure 5-22 Simple Domain Selected in the Select Data Dialog 


3. Select the domain you want to use. 

4. Click Choose Data, the Data Chooser opens to the Fields page. 

You are now ready to configure your data using the Data Chooser Wizard. 


.8.1 Referential Integrity 

When you create an Ad Hoc view from a Domain, the two elements are connected - the data in the view is 
dependent on the Domain. This relationship affects users working with the Domain and the dependent view in a 
number of ways: 

• When an item or items from the Domain are used in the dependent Ad Hoc view, removing the items from 
the Domain will result in a Missing Data error message when opening the Ad Hoc view in the editor. The 
user is prompted to remove the items from the Ad Hoc view. The removed items no longer appear in the 
Data Source Selection panel when the editor opens. 
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Items not used in dependent views can be removed from the Domain by the Domain’s administrator; those 
items no longer appear in the view's Available Fields list. 


5.8.2 Using the Data Chooser Wizard 

To design a Domain Topic or a view based on a domain, use the Data Chooser wizard. To open the Data 
Chooser wizard: 

1. Click Create > Ad Hoc View. 

2. Click and browse to a Domain, then click Choose Data to access the following pages of the Data 
Chooser: 

• The Select Fields Page - Choose the fields to make available in the Ad Hoc Editor. 

• The Pre-filters Page - Define a filter on any field, with the option of prompting for user input, or to 
compare fields. 

• The Display Page - Change the order and names of fields that appear in the Ad Hoc Editor. 

• The Save as Topic Page - Save the settings as a Domain Topic. 

You must start by selecting some fields on the Select Fields page, but the other three pages are optional and can 
be completed in any order. Click Table, Chart, or Crosstab at any time to begin designing a view based on 
the chosen data. 

5.8.2.1 The Select Fields Page 

Use this page to choose fields and sets of fields to use in the view or make available in the Domain Topic: 



Figure 5-23 The Fields Page of the Data Chooser 

• The Source panel displays the sets of fields in the Domain. Use ▼ and ► to collapse or expand each set. 

• The Selected Fields panel shows the items you selected. You can move a field or set back and forth 
between the panels by dragging, double-clicking, or selecting the item and clicking an arrow button, such 
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► 

as 

• When you select any field from a set in the Source panel, the set name appears with the field in the 
Selected Fields panel, If you do not want sets, use the settings on the Display page. 

• Some Domains define sets that are not joined, also called data islands. When you select a field from such a 
set, the behavior on the Select Fields page depends on how the joins were created in the Domain: 

• If the Domain uses basic joins, the unjoined sets aren’t available. The Domain Designer only creates 
basic joins. 

• If the Domain uses advanced joins, all joins are available regardless of the join set of the fields you 
add. In this case, you must manually make sure that you do not add fields that are in different data 
islands to a single Ad Hoc view. Otherwise you will receive errors when attempting to work with the 
view. 

5.8.2.2 The Pre-filters Page 

You can pre-filter data in the Data Chooser before launching the Ad Hoc Editor or creating a Domain Topic. 
Pre-filtering data limits the data choices available in a Domain Topic or the fields that ultimately appear in the 
Ad Hoc view. You can also define a filter on a field that does not appear in the final report. The filter is still 
applied and only data that satisfies all defined filters appear in the final report. For example, you can filter data 
to select a single country, in which case it doesn’t make sense for the Country field to appear as a row, column, 
or group. You can also design reports that prompt users to input data to use as a filter. 

The Pre-filters page provides powerful functionality for designing views within the server. 


Data Chooser 


Cancel 


Pre-filters 

Create filters here to limit the data available in the editor. Double-click a field to begin. 



Fields 
V Accounts 

Account Name 
Account City 
Account State 
Account ZIP 
Account Industry 


Filters 


Account Name is one of 
Available Values: 


Selected Values; 


Burkhardt-Whitney Engineering, 
Welsh-McCollum Transportation ■ 
Jaramillo-Compagno Telecommu" 
D & G Burkhardt Transportabon, 

N & 0 Gamer Electronics, Inc 
H &.Y Evans Engineering, Inc ^ 


Cancel 


D Locked 


Figure 5-24 Condition Editor in the Filters Panel on the Pre-filters Page 
To define a filter: 

1. In the Data Chooser, click Pre-filters. 

2. Expand the options in the Fields panel. 

3. Double-click to select a field in the Fields panel. Choices appear for filtering the selected field: 
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4. Choose a comparison operator. 

Text fields have both substring comparison operators such as “starts with” or “contains” and whole string 
matching such as “equals” or “is one of” When you select a whole string matching operator, a list appears 
showing all existing values for the chosen field retrieved in real-time from the database. 

In the Filters panel, a drop-down appears containing the account names from which you can select multiple 
values. 

5. Click each value for comparison in Available Values to move it to Selected Values. The account names 
appear in Selected Values. 



If there are more than 50 Available Values, click ^ to search for the value. The maximum number of 

items that can be displayed in Available Values is configurable. For details, see the TIBCO 
JasperReports Server Administrator Guide. 


6. To limit the view design to the four account names in Selected Values, check the Locked check box. 

By default, the Locked check box is unchecked, making the filter available to end-users mnning the report. 
In the Report Viewer, users can click the Options button to enter a comparison value for this condition; 
when the user clicks Apply or OK, the report preview refreshes with data that match the condition. The 
condition is available as a prompt even if the filtered field does not appear in the report. For example, the 
final report might present data for a single country, but the country is chosen by the user. Once defined, 
filter prompts can be modified in the Ad Hoc Editor, as explained in ^‘Using Input Controls” on page 161. 
Note that when the Locked check box is checked, the filter is not available to end-users mnning the report. 
The condition can be removed from the view, if needed, but not edited. 

7. Click OK to create the filter. 

The Filters panel shows the filters you have defined. 

8. In the Filters panel, click Change to modify the condition. Click OK to save the changes. After selecting 
a row, you can also click Remove to delete it from the list. 


Data rows must match all conditions. In other words, the overall filter applied to the data is the logical AND 
of all conditions you have defined. 


5.8.2.3 The Display Page 

Use the Display page to change the default label and order of the fields as they should appear in the list of 
fields in the Ad Hoc Editor. You can always change the field labels and ordering in the Ad Hoc Editor, but 
setting them here makes them available in a Domain Topic. The page includes these options: 

• To change the order of fields, click once anywhere in a field’s row and use the Move to top. Move up. 
Move down, or Move to bottom buttons: 

A A ▼ ▼ 

, , ,and 

Fields may be moved only within their set, but sets as a whole may be also be moved. 

• By default, the field name becomes the display label for the row, column, or measure that you create from it. 
To change the default display label of a field or set, double-click anywhere in the row and type the new 
label in the text box. 

• Sets and the fields they contain appear in the list of fields in the Ad Hoc Editor. Sets are not used in views, 
but can be used to add all their fields at once, expediting view creation. 
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• If you don’t want to use sets in the Ad Hoc Editor, select Flat List at the top of the Data Source Selection 
panel. You can now relabel the fields and reorder them. 

5.8.2.4 The Save as Topic Page 

Here you can enter a name and a description to save the Data Chooser settings as a Domain Topic. Thereafter, 
you can create different views from the Domain Topic, using its fields, filters, and display label settings. You 
can also edit the Domain Topic to change the settings. 

If an administrator has enabled the Data Staging feature, you can turn data staging on for your domain topic. 
With data staging, the entire dataset for a Domain Topic is indefinitely cached in the server’s Ad Hoc cache. Ad 
Hoc views and reports from that Domain Topic mn faster because they fetch data from the local cache, not by 
queiying the production database. To keep data fresh, you can specify a refresh interval, and the server will 
periodically access the database in the background to reload the entire dataset. 

• By default. Domain Topics are saved in the standard Topics folder. This corresponds to the Ad Hoc 
Components > Topics location in the repositoiy; JRXML Topics and Domain Topics in this folder 
appear on the Topics tab when you start a view. Do not modify this folder name. 

• The description text appears with the Domain Topic in the repository and at the bottom of the Topics tab 
on the Ad Hoc Source dialog. Enter an informative description that helps users understand the nature and 
purpose of this Domain Topic. 


.9 Working with Topics 

When a user clicks Create > Ad Hoc View on the Home page, the Select Data wizard offers a path to a list of 
Topics populated from the Ad Hoc Components/Topics folder in the repositoiy. There are two types of Topics: 

• JRXML-based Topics - Created by administrators using Jaspersoft Studio and uploaded as JRXML files to 
the proper location in the repository. Topics are typically of this type. 

• Domain Topics - Created from a Domain by administrators using JasperReports Server. 

Either type of Topic is an empty view associated with a data source in the server, and is then built on in the Ad 
Hoc Editor. 


.9.1 Uploading a Topic Through the Web Ul 

JRXML-based topics are the most common type of topic. You can upload previously created JRXML topics via 
the repository. 

To upload a JRXML-based Topic: 

1. Log into the server as administrator and select View > Repository. 



While any user with sufficient repository permissions can upload a Topic to the server, this example 
requires an administrator login to access the JServer Jdbc data source. 


2. Locate the folder where Topics are stored. The location of the Topics folder depends on your system 
configuration; by default. Topics are in the Ad Hoc Components > Topics folder. 

3. Right-click the Topics folder name and select Add Resource > JasperReport from the context menu. 
The Set Up the Report page of the JasperReport wizard appears. 
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Add Resource appears on the context menu only if your login account has write privilege to the 
folder. 


4. In the Set Up the Report page, give the Topic a name, a Resource ID, and an optional description, then 
click Next. 

• The Name field is the visible name of the file in the repositoiy, such as Example Topic. 

• The Resource ID field is the internal ID of the object, such as Example_Topic. The server does not 
accept spaces in an internal ID. 

• The Description field, such as Topic uploaded for User Guide example, helps users understand 
the purpose of the file. 

5. In the Locate the JRXML File section, select Upload a Local File, and click Browse to locate the file 
and upload the Topic from the file system. In this example, the file is <js- 
install>/samples/adhoc/topics/adhoc_sample.jrxml. 



To locate adhoc_sample.jrxml, you need access to the server host file system. 


6. Click Data Source. 


Because this is a simple Topic without parameters, there are no controls and resources associated 
with it. If the Topic has a Parametrized query, you can create input controls for it. See “Selecting a 
Data Source for Running the Complex Report” on page 200. Such input controls can appear in the 
Ad Hoc Editor and when the report is run. 


7. Click Select data source from repository and Browse to locate the data source named Data 
Sources/JServer Jdbc data source. 

8. Select Data Source, then click Select. 

Topics must be associated with the data source that they were designed for. 

9. Click Submit at the bottom of the screen. 

Topics usually do not need a query or customization, but you can define them. 

When you select Create > Ad Hoc View and click in the Select Data wizard, you can browse to Ad Hoc 
Components > Topics. If you select the Example Topic, you can create a report using the columns available 
in the data source selected in step 7. 


The JRXML file that the Topic is based on must contain a query and a field list. 



Any report layout in the Topic’s JRXML file is ignored by the Ad Hoc Editor. We recommend that a Topic’s 
JRXML file not include anything other that the query and field list. 


When you create a JRXML file for use as a Topic, you can specify the name to display for each field that the 
Topic returns. To do so, define a field property named adhoc. display for each field declared in the JRXML. 
The adhoc.display field property must have the following syntax: 

<property name="adhoc.display" value="Any Name"/> 


If the Topic includes fields with unusual datatypes, those fields don't appear in the Ad Hoc Editor because 
it's not equipped to manage them properly. For example, if the Topic is defined against a MongoDB 
instance that returns data of type array, this field isn't available in the Ad Hoc Editor. For more information 
on datatype support in the Ad Hoc editor, see the TIBCO JasperReports Server Administrator Guide. 
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For example, this JRXML code declares a StoreState field that is displayed in reports as Store State: 

<field name="StoreState" class="java.lang.String"> 

<property name="adhoc.display" value="Store State"/> 

</field> 

Topics also support the $R expressions for field names; for more information, see “Localizing Reports” on 
page 204. 

For fields in a non-domain topic the following properties may be of interest: 

• dimensionOrMeasure: marks a field as a field or a measure 

• defaultAgg: which aggregation should be used for this measure (avg, etc) 

• semantic, item.desc: A description for the field 

• defaultMask: set a measure as a $, date etc 

For more information on working with JRXML topics, see the TIBCO Jaspersoft Studio User Guide. 


.9.2 Creating Topics from Domains 

In some circumstances it is important to create a Topic based on the Domain and data settings you chose, but 
ifs not always necessaiy. The main consideration is how reports based on the Domain-based view are used. The 
following table explains the choices. 


If you want to ... 

Then do this 

Explanation 

Create a single-use report 
from the Domain with your 
settings. 

Click Table, Chart, or 

Crosstab after defining your 
settings in the Data Chooser, 
then format the view and 
create your report. 

Your field selections appear in the Ad Hoc 
Editor and you can create views from them, 
but the settings themselves are not saved. 

Run a report repeatedly as is 
or with prompting for new 
input, or make very similar 
reports in the Ad Hoc Editor. 

Click Table, Chart, or 

Crosstab after defining your 
settings in the Data Chooser, 
then format and save the view 

in the Ad Hoc Editor. 

After you save a view, users can create 
reports to be run from it repeatedly and be 
prompted for input each time if you defined 
unlocked filters. 

Reuse your field, filter, and 
display settings on this 

Domain to create new views 
with different formatting. 

After saving your settings as a 
Domain Topic in the Data 
Chooser, start a new view and 
choose your Domain Topic 
from the Domains tab. 

Domain Topics are saved in JRXML format 
in the repository. They appear on the Topics 
tab when you start a view. 

Be able to modify one or more 
of the settings you made in 
the Data Chooser wizard. 

After saving your settings as a 
Domain Topic in the Data 
Chooser, find your Domain 
Topic in the repository and 
open it in the Domain 

Designer. 

Domain Topics can be edited as described 
in “Editing a Domain Topic ” on page 173. 
After you save your changes, you can create 
views based on the modified Domain Topic. 
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If you want to ... 

Then do this 

Explanation 

Create views from the same 
repository data source but 
with different Domain settings, 
such as derived fields and 
different joins to make new 
fields available in a report. 

Edit the Domain and save it 

with a new name. Then start a 
new view and choose your 
data from the new Domain. 

Domains provide advanced functionality 
such as table joins and derived fields based 
directly on a data source. Domains usually 
require administrator permissions to create 
and modify. 



Ad Hoc views based on Domain topics may return duplicate data if Data Staging is enabled. 


5.9.2.1 Access Permissions in Domain Topics 

If other users create reports from your Domain Topic-based view, and the Domain is configured for security, ifs 
important to consider everyone’s access permissions. You might not have access to all of the fields in the 
Domain nor to all the data in those fields. There may be fields that can be seen only by other users, and in the 
fields that you can see, some data may be hidden from you. When you save the Domain as a Topic, only the 
fields that you selected appear in the Domain Topic. When you create a view from the Topic, only the data that 
you can access in those fields appears. When others create views from the Topic, they see only fields that they 
have permission to access. These mles also apply to the reports generated from these views. 

For example, in a Domain, user Tomas can access fields B-C and data rows 1-3; Anita can access fields C-E and 
data rows 2-5. Tomas uses the Data Chooser and saves a Domain Topic based on the Domain. When Tomas and 
Anita create reports from the same view, they see different combinations of fields and the data in them. 



Fields 

Data 

Tomas's report from his Domain Topic 

BC 

1 23 

Anita’s report from the same Domain Topic 

C 

2345 


Even though Anita has permission to see more fields, they're not available to her because Tomas did not have 
access to them when he created the Domain Topic. However, Anita does have permission to see more data than 
Tomas, so when she creates a view, or opens or mns the report based on that view, she can see more rows than 
Tomas can when he views the report. See the TIBCO JasperReports Server Security Guide for a technical 
explanation of data security for Domains. 

5.9.2.2 Saving Domain Settings as a Domain Topic 

To save settings in the Data Chooser wizard as a Domain Topic: 

1. While making selections in the Data Chooser, navigate to the Save Topic page. 

2. Enter a Topic name and description. 

Do not change the location folder. Using the default /adhoc/topics folder makes the saved Domain Topic 
available in the Ad Hoc Components > Topics folder when you select Create > Ad Hoc View. 

3. If your data selections, filter definitions, and display settings are complete, click Table, Chart, or 
Crosstab. 


172 


TIBCO Software Inc. 













Chapter 5 Working with the Ad Hoc Editor 


If settings are incomplete, navigate to the other pages to finish, then click Table, Chart, or Crosstab 


The new Topic appears in the Ad Hoc Components > Topics folder. 

Because a Domain Topic is a type of report, it appears when the Search page is filtered to show reports: 

5.9.2.3 Editing a Domain Topic 

You can modify a Domain Topic you created using the Data Chooser. 

To edit the settings in a Domain Topic: 

1. Select View > Repository and search (or browse) for the Domain Topic you want to modify. Domain 
Topics are usually kept in the Ad Hoc Components > Topics folder. 

2. Right-click the Domain Topic and select Open in Designer from the context menu. The Domain Topic 
opens in the Data Chooser wizard. 

3. Follow the guidelines in ^‘Using the Data Chooser Wizard” on page 166 to edit the Domain Topic as 
needed. 

4. To save changes to the selected Domain Topic, click Table, Chart, or Crosstab on any page. 



Use caution when editing Domain Topics that may have been used to create other views. Users relying 
on the Domain Topic might receive unexpected data or errors. It's safer to save changes as a new Domain 
Topic. 


To save changes as a new Domain Topic, navigate to the Save as Topic page and enter identifying information 
for the new Topic, then click Table, Chart, or Crosstab. 
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This section describes functionality that can be restricted by the software license for JasperReports 
Server. If you don’t see some of the options described in this section, your license may prohibit you from 
using them. To find out what you're licensed to use, or to upgrade your license, contact Jaspersoft. 


Using the Ad Hoc Editor, you can create reports within JasperReports Server from pre-defmed Topics and 
Domains. You can also create reports outside of JasperReports Server and add them to the repository. To add a 
report to the repository, you need a valid JRXML file. To create and validate this file, you can use Jaspersoft 
Studio. Jaspersoft recommends Jaspersoft Studio for most users because its graphical user interface simplifies the 
job. If you have a thorough understanding of the file stmcture, you can use a text editor to create the file 
containing JRXML code. 

You can add a report to the server’s repository in two ways: 

• From within the server 

Add the JRXML file and any other resources the report needs as a report unit. A wizard guides you through 
each step. 

• From Jaspersoft Studio 

Design the report in Jaspersoft Studio, and use a connection to JasperReports Server to add the JRXML and 
resources to the JasperReports Server repository. See the TIBCO Jaspersoft Studio User Guide for 
information. 

To add the sample report units to the server, you need access to the sample data in the server installation 
directory on the file system (<js-install>/samples). Contact your administrator for help in locating these files. 



In most cases, it is preferable to upload the JRXML file from Jaspersoft Studio. Uploading through 
JasperReports Server is included for completeness. 


This chapter includes examples of adding a report to the repository using the server’s wizard and the plug-in. 
The chapter contains the following sections: 

• Overview of a Report Unit 

• Adding a Report Unit to the Server 

• Modifying the Query When Uploading a Report 

• Adding a Complex Report Unit to the Server 

• Adding Cascading Input Controls to a Report 

• Editing JRXML Report Units 

• Localizing Reports 
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.1 Overview of a Report Unit 

In the server, a report unit is the collection of elements used for retrieving data and formatting output. Figure 6- 
1 on page 176 shows these elements: 

• The data source and the queiy that retrieves data for the report. 

• The main JRXML that determines the layout and is the core of the report unit. 

• The main JRXML defines other elements in one of the following ways: 

• Creating definitions internally 

• Referring to existing elements in the repositoiy using the repo : syntax 

• The input controls and other resources. 

For more information about the report unit, refer to the TIBCO JasperReports Server Ultimate Guide. 



t: 

Data Source 

Queiv 





t 1 



Input Controls 

' ^ . 


Main JRXML 


Resources 



Figure 6-1 Anatomy of a Report Unit 
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.2 Adding a Report Unit to the Server 

This section presents an example of uploading a JRXML with resources to the server. This report has two 
images that need to be added. 


2.1 Selecting the Main JRXML File 

If you want to validate the JRXML before uploading it, use Jaspersoft Studio. The server doesn’t validate the 
JRXML when you upload it. 

This procedure shows you how to set up a name for the report in the repository and select the main JRXML file 
that references all other elements. 

To upload the main JRXML for this example: 

1. Log into the server as administrator and select View > Repository. 


If you log in as a user, you can upload a report unit to the server, but this example requires an 
administrator login to access the image resources. 


2. Locate the folder where you want to add the report. For example, go to Public > Samples > Reports. 

3. Right-click the Reports folder and select Add Resource > JasperReport from the context menu. The Set 
Up the Report page of the JasperReport wizard appears. 


Add Resource appears on the context menu only if you have write permission to the folder. 


4. In Naming, enter the name and description of the new report and accept the generated Resource ID: 

• Name - Display name of the report: New Simple Report 

• Resource ID - Permanent designation of the report object in the repository: New_Simple_Report 

• Description - Optional description displayed in the repository: This is a simple example 

5. Select Upload a Local File and Browse to <js-install>/samples/reports/AllAccounts.jrxml. 


This example shows how to upload a JRXML 
can also select a JRXML from the repository. 


file from the samples folder in the installation directory. You 


In Figure 6-2 you can see the Set Up the Report page. 
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Add JasperReport: New Simple Report 

Set Up the Report 

Set the required values for the report, then, optionally, proceed to other pages in the flow. 


Setup 


Controls & Resources 


Data Source 


Query 


Customization 


Name: 

New Simple Report 


Resource ID (required): 

N e w_S i m p I e_Re po rt 

Description: 

This is a simple example 


Locate the JRXML File 
(!) Upload a Local File 
AllAccounts.jrxml 


Q Select a JRXML from the Repository 


Submit 


Cancel 


Figure 6-2 Required Set Up Values 
6. Click Controls & Resources. 

The Controls & Resources page appears. If the server detects that the report needs additional resources, 
you'll be prompted to locate those resources. 
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Add JasperReport: New Simple Report 



Controls & Resources 

Locate the controls and resources used by your report. 

Resources 

LogoLink 

AllAccounts_Res2 

Add Resource... 

Input Controls 
Add Input Control... 

Input Control Options 
Display Mode: 

I Pop-up window ^~| Q Always prompt 
Optional JSP Location: 


Add Now 
Add Now 


(within /WEB-INF/jsp) 


Figure 6-3 Suggested Resources in the Resources List 

A JRXML file doesn’t embed resources, such as images. When the server uploads the JRXML, it tries to 
detect any missing resources. For example, Figure 6-3, ‘‘Suggested Resources in the Resources List,” on 
page 179 shows that two image files are missing: 

• LogoLink 

• AllAccounts Res2 


6.2.2 Uploading Suggested File Resources 

If needed files are missing, as shown in Figure 6-3, you need to take one of the following actions: 

• Upload resources that the report needs 

• Select a resource from the repository 


If the Controls & Resources page doesn’t suggest resources, perhaps the report doesn’t reference any. 
However, the server can’t always detect all the referenced resources, as discussed in “Uploading 
Undetected File Resources” on page 187. 


To upload a resource from the file system: 

1. On the Controls & Resources page, click Add Now in the row of the missing resource, for example, 
LogoLink. The Locate File Resource page appears. 

2. Choose Upload a Local File then click Choose File. 

3. Browse to <js-install>/samples/images. The LogoLink file is not available, but you can use an alternate 
image, such as <js-install>/samples/images/jasperreports.png. 

4. Click Open to return to the Locate File Resource dialog. 
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5. Click Next. The Add a Report Resource page appears. 


Add JasperReport: New Simple Report 

Add a Report Resource 

Set the properties for the resource. 


Type: image 

Selected Resource: 
jasperreports.png 

Name (required): 
LogoUnk 

Resource ID (read-only): 
LogoLink 

Description: 

LogoLink 


Previous Next Cancel 


Figure 6-4 Properties of a Resource 


The properties include the LogoLink name, resource ID, and description. 


6. Click Next to accept the default naming of the file resource. 

The Controls & Resources page appears again, showing that the LogoLink resource was added. 

To add a resource from the repository: 

1. To add the second resource, click Add Now in the row for AllAccounts_Res2. 

2. Choose Select a resource from the Repository and Browse to an image file, for example. Public > 
Samples > Images > Jaspersoftjogo.png. 



Any image file works. 


3. Click Select. 

The path to the image appears in the wizard. 

4. Click Next. The Add a Report Resource page displays the properties of the image as set in the uploaded 
JRXML file. 


The properties include the LogoLink name, resource ID, and description. These properties don’t 
redefine the properties of the Jaspersoftjogo.png file in the repository. 


5. Click Next to accept the default naming of the file resource. 
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The Controls & Resources page reappears, showing the addition of both resources referenced in the main 
JRXML. 

6. Click Data Source and define a data source as described in the next section. 


6.2.3 Defining the Data Source 


Data sources are not defined directly in the report JRXML file and must be specified when you upload a file to 
JasperReports Server. On the Data Source page of the Add JasperReport wizard, you can select a data source in 
the repositoiy or create a new data source on-the-fiy. 

If you want to create a data source, the application server must be able to find the driver for the database you 
want to use. For example, in a default installation of JasperReports Server, Tomcat looks for data source drivers 
in <js-install>/apache-tomcat/lib. Put a copy of the driver in this location. 

To define a data source for the simple report example: 

1. In the JasperReport wizard, click Data Source. The Link a Data Source to the Report page presents these 
choices: 

• Do not link a data source - Select or define the data source at a later time. You see an error if you mn 
the report in this state. 

• Click here to create a new data source - Define a new data source available only to your report. 

• Select data source from repository - Select an existing data source from the repository. 

2. Choose Select data source from the Repository and Browse to Public > Samples > Data sources > 
JServer JNDI Data Source. 

3. Click Select. The Link a Data Source to the Report page reappears with the path to the data source. 

Add JasperReport: New Simple Report 


Link a Data Source to the Report 


Optionally, link a data source to the report. You can choose a data source from the repository or create a new one. 



O Do not link a data source 


O C ck here to create a new dara source 


(•) Select data source from repository 


/public/Samples/Data_Sources/JServerJNDIDS 


Browse... 



Cancel 


Figure 6-5 Data Source Page 


4. Click Submit to add the new report unit to the repository. 
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6.2.4 Saving the New Report Unit 

To submit a new report unit to the repository, click Submit on any page of the JasperReport wizard, from the 
Set Up page to the Customization page. You don’t have to set options you don’t need, such as Customization. 
When you click Submit, the server attempts to upload the report JRXML and its resources. If the upload is 
successful, a message appears at the top of the repository page, indicating that the report was saved. The report 
appears in the repository with the description you entered on the Set Up page. To mn the report and view the 
output, click its name. New Simple Report. 


Repository 


Folders 


Run Edit c Copy Cut r : 

Delete 


Sort By; 

Name Modified 1 

► H Auait 


© Name 

Description 

Type 

Created Date 

Modified Date 

> B Diagnostic 

p H Monitoring 


11. Sales By Month Report 

Sample multi-panel report 

Report 

July 15 

10/16/2019 

-r H Samples 


12. Promotion Details Report 

Drill-through from the Supermart dashboard. 

Report 

July 15 

10/9/2019 

p H Ad Hoc Vie... 

1 

14. World Map 

Report with simple Geographic Map and Hyperlink 

Report 

July 15 

10/11/2019 

p hI Dashboards 

1 






p Si Dau Sour... 

1 

16. Interactive Sales Report 

Interaaive table and chart. 

Report 

July 15 

8/27/2019 

1 




p Si Domains 


17. Report Workbook 

Sample report book with table of contents. 

Report 

July 15 

10/27/2015 

p m OLAP 


20.1 Account List 

Sample Report used for basic Visualize.js demo 

Report 

July 15 

5/16/2014 

p -a Reports 

1 

20.2 Cities 

Sample Report used for basic Visualize.js demo 

Report 

July 15 

4/24/2014 

p H Resources 

1 






p a Templates 


20.3 SalesPerCityReport 

Sample Report created from Ad Hoc View for Basic Visualize.js Demo 

Report 

July 15 

4/24/2014 







p a Temp 


20.6 Store Details 

Sample Report used for basic Visualize.js demo 

Report 

July 15 

4/24/2014 

p a Themes 


New Simple Report 

This is a simple example 

Report 

Today 

Today 


Figure 6-6 New Report Added to the Repository 

In the report viewer, click ^ to go to the end of the report, where the logo images that you added appear. The 
following figure shows the output. 


la. 


— 100% ▼ search report 


Q - 


ii 4 Page 47 


1 Name 

Phone 

Address I 

10. Taryle-Spencer Transportation 

Holdings 

470-555-2278 

3732 Camino Norte 

11. K & R Brandon Communications Group 

315-555-7829 

8067 Olympic Drive 


QJASPER JasperJsoft 

H r p o R I & 


Figure 6-7 Output of the New Simple Report 


6.3 Modifying the Query When Uploading a Report 

The queiy in the report unit determines the data that the server retrieves from a data source. You can create 
multiple reports that look the same but contain different data by defining different queries for the same JRXML 
file each time you upload it. You can choose use a stored queiy in the repository or define a new one. This 
example uses a query that returns accounts from a single country. 

You can only override the main query for a report (specifically, the query defined directly within the JRXML 
root element <jasperReport>). If the report has elements that use a sub-dataset (including all table elements 
and all elements that use a different dataset), the queries for these elements will not be affected. 
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First you need to upload the report and select a data source, as in the previous example. Then you can create a 
queiy which replaces the original queiy in the report. 

To locate the sample report for this example: 

1. Log into the server as administrator and select View > Repository. 

2. Locate the folder where you want to add the report. For example, go to Public > Samples > Reports. 

3. Right-click the Reports folder and select Add Resource > JasperReport from the context menu. The Set 
Up the Report page of the JasperReport wizard appears. 


Add Resource appears on the context menu only if you have write permission to the folder. 


4. In Naming, enter the name and description of the new report and accept the generated Resource ID: 

• Name - Display name of the report: Sample Query Report 

• Resource ID - Permanent designation of the report object in the repository: Sample_Query_Report 

• Description - Optional description displayed in the repository: Example of changing a query in 
a report 

5. Select Upload a Local File and Browse to <js-install>/samples/reports/SimpleReport.jrxml. 

6. Click Open to upload the file. 

To select a data source for the report: 

1. In the Add JasperReport wizard, click Data Source. The Link a Data Source to the Report page appears. 

2. Choose Select data source from the Repository and Browse to Public > Samples > Data sources > 
JServer JNDI Data Source. 

3. Click Select. The path to the data source appears on the page. 

To define a custom query for the simple report example: 

1. In the Add JasperReport wizard, click Query. The Locate Query page presents the following choices: 

Do not link a Query - Select this option to use the existing queiy already defined within the main 
JRXML. 

Click here to create a new Query - Guides you through defining a new query for this report only. 
Select a Query from the Repository - Select this option to use a saved query from the repository. 

The SimpleReport.jrxml file already contains a query. Choosing the second or third option overrides the 
existing query by defining a new one. 
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Add JasperReport: Sample Query Report 

Locate Query 

0 Do not link a Query 
(•) Click here to create a new Query 
0 Select a Query from the Repository 




Submit 


Setup 

Controls & Resources 
Data Source 
Query 

Customization 


Figure 6-8 Query Page 

2. Select Click here to create a new Query. The link becomes active. 

3. Click the link, Click here to create a new Query. The Add Queiy wizard appears and displays the Name 
the Queiy page. 

4. Enter the name, resource ID, and description of the queiy. The queiy in this example retrieves only Mexican 
accounts. Enter the following values: 

• Name — MexicoAccounts 

• Resource ID — MexicoAccounts 

• Description — Query for example in User Guide 

This query and its properties are visible only within the report unit. 


Add Query: 


Name the Query 

Enter the required property values. 


• Name the Query 
Link a Data Source 
Define the Query 


Name (required): 
MexicoAccounts 


Resource ID (required): 
MexicoAccounts 


Description: 

Query for example in User Guide 


Pi^vimiS. Next Cancel 


Figure 6-9 Name the Query Page 

5. Click Next. The Link a Data Source to the Queiy page appears. Here you have the option to select a data 
source to use only with this query. This can be different from the data source you selected for uploading the 
report. You can choose an existing data source from the repository, define a new one, or select not to link a 
data source. 

6. Select Do not link a data source to use the same data source you already selected. 
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7. Click Next. The Define the Query page appears. 

8. Select SQL in the Queiy Language drop-down and enter the following queiy string to retrieve only 
Mexican accounts: 

SELECT FROM accounts WHERE billing_address_country = 'Mexico' ORDER BY billing 
address_city 

Add Query: MexicoAccounts 

Define the Query 

Select a language and enter the query 

Name the Query Query Language: I SQL ▼ | 

Link a Data Source 

rv r- ^ Query string: 

• Define the Query - 

SELECT * FROM accounts WHERE billing_address_country = ’Mexico' ORDER BY billing_address_city 


Save 


Figure 6-10 Definition of a Query 

9. Click Save to save the query. The Customization page appears. No customization is required for the 
example. 

10. Click Submit to submit the new report unit to the repository. 

To run the report: 

1. Locate the report in the repository and click to mn it. Only accounts in Mexico are shown in the report. 

Back 0 ▼ R ▼ — + 100% ▼ search report ^ Page 1 of 5 ^ ^ 


Accounts 


Name 

Phone 

Address 1 



1. 

Bruno-Bowers Communications Associates 

737-555-2156 

9650 Valley View Road 


Brown-Giglio Electronics, Ltd 

295-555-3431 

1962 Geary Road 

3. 

Q & Q Bergin Telecommunications 
Associates 

218-555-2598 

2810 Guadalupe 

"T" 

N & W Hill Transportation Corp 

422-555-1772 

7572 Easley Drive 

5. 

M & Y Browqett Communications, Ltd 

373-555-4575 

5312 Riverwood Circle 

6. 

Sherwood'Becker Transportation Holdings 

761-555-9439 

9825 Mt. Dell Drive 

7. 

Trujillo-Barrington Machinery, Inc 

754-555-9987 

9865 Montana 


Figure 6-11 Output of the Report 
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4 Adding a Complex Report Unit to the Server 


This section includes an example of how to add a report unit with all these resources: 

• SalesByMonth.jrxml - the main JRXML file 

• SalesByMonthDetail.jrxml - a subreport 

• sales.properties - an English resource bundle file 

• scriptlet.jar - a scriptlet class JAR file 

• JR Logo - an image in the repository 

• JServer JNDI data source - a data source file in the repository 

These resources are part of the sample data installed with the server. To complete this example and mn the 
report without server errors, you need access to these resources. 

The example also guides you through defining every type of input control: 

• Text 

• Check box 

• Drop-down 

• Date 

• Query 

If you’re not interested in creating all types of input controls, but want to work through part of the example, 
delete parameters for the input controls you don’t create before you mn the report. 

The complex report you create in this example is almost exactly like the SalesByMonth report in the Reports 
folder of the repository. 

To upload the main JRXML and suggested resource files for the complex report unit: 

1. Log into JasperReports Server as administrator and select View > Repository. 



If you log in as a user, you can upload a report unit to the server, but this example requires an 
administrator login to access the image resources. 


2. Navigate to the folder containing your report. For example, navigate to Organization > Reports. 

3. Right-click the Reports folder and select Add Resource > JasperReport from the context menu. The Set 
Up the Report page appears. 



Add Resource appears on the menu only if you have write privilege to the folder. 


4. Enter these properties: 

• Name — New Complex Report 

• Resource ID — New_Complex_Report 

• Description — This is a complex report 

5. Select Upload a Local File and Browse to <js-install>/samples/reports/SalesByMonth.jrxml. 

6. Click Controls & Resources. 

The Controls & Resources page. Figure 6-12, suggests resources to be uploaded for the report: 

• A sub-report (the SalesByMonthDetail.jrxml file) 

• A logo image 
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Add JasperReport: New Complex Report 


Controls & Resources 


Data Source 


Customization 


Controls & Resources 

Locate the controls and resources used by your report. 

Resources 

SalesByMonth Detail 
Logo 

Add Resource 


Input Controls 
Add Input Control. 

Input Control Options 
Display Mode: 

I Pop-up window | ( 1 Always prompt 

Optional JSP Location: 

(within /WEB-INF/jsp) 


Add Now 
Add Now 


Submit 


Figure 6-12 Suggested Resources for the Complex Report 

7. On the Controls & Resources page, upload the sub-report: 

a. Click Add Now in the SalesByMonthDetail row. The Locate File Resource page appears. 

b. Select Upload a Local File. 

c. Click Browse and locate the file <js-install>/samples/reports/SalesByMonthDetail.jrxml. Select 
SalesByMonthDetail.jrxml. 

The path to SalesByMonthDetail.jrxml appears in the Upload a Local File field. 

d. On the Locate File Resource page, click Next. 

e. On the Add a Report Resource page, click Next to accept the default report resource name and resource 
ID. 

8. On the Controls & Resources page, upload the logo image resource: 

a. Click Add Now in the Logo row. The Locate File Resource page appears. 

b. On the Locate File Resource page, click Select a resource from the Repository. 

c. Click Browse to locate the file /Images/JR Logo and select JR Logo. 

d. Click Next. The Add a Report Resource page appears. 

e. On the Add a Report Resource page, click Next to accept the default name, resource ID, and 
description. 


.4.1 Uploading Undetected File Resources 

The JasperReport wizard can’t detect every type of resource referenced in the main JRXML. You need to add 
the undetected resources before the server can upload the report. For the following example we provide the 
names of these resources. To discover undetected resources open the JRXML in Jaspersoft Studio and examine 
its parameters and properties. For more information about the JasperReports Server Plug-in, see the TIBCO 
Jaspersoft Studio User Guide. 

These are the undetected resources in the SalesByMonth.jrxml: 
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• A scriptlet JAR - The scriptlet writes the message, ‘T’m a scriptlet in ajar,” to the last page of the report 
output. 

• An English language resource bundle. 

• The optional Romanian language resource bundle. 

If you’re interested in working with a multi-lingual report, add the Romanian resource bundle. The 
Romanian resource bundle is part of the sample data installed with the server. 

On the Controls & Resources page, upload the undetected resources to the server using exactly the same name 
Jaspersoft Studio uses for the resource ID. 

To upload the undetected file resources for the complex report example: 

I. Add and upload the scriptlet JAR file: 

a. On the Controls & Resources page, click Add Resource. 

b. On the Locate File Resource page, select Upload a Local File and Browse to the <js- 
install>/samples/jars/scriptlet.jar file. Select scriptlet .jar. 

The path to the file appears in the Upload a Local file field. 

c. Click Next. 

The Add a Report Resource page appears. Figure 6-13 on page 188 shows the file name scriptlet .jar, 
indicating that the server successfully loaded and automatically detected the JAR. 

d. Enter the following information: 

• Name — Scriptlet 

• Resource ID- Scriptlet. The Resource ID is referenced in the main JRXML file, so do not 
change it. 

• Description — Scriptlet JAR for complex report 

Figure 6-13 on page 188 shows these values entered on the Add a Report Resource page. 


Add JasperReport: New Complex Report 

Add a Report Resource 

Set the properties for the resource. 


Type: jar 

Selected Resource: 
schptlet.jar 

Name (required): 

I Scriptlet 

Resource ID (required): 

[ Scriptlet 

Description: 

Scriptlet JAR for complex reports. 


Previous Next Cancel 


Figure 6-13 Scriptlet JAR Resource Properties 
2. Click Next. 
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3. Add and upload the English resource bundle: 

a. On the Controls & Resources page, click Add Resource. The Locate File Resource page appears. 

b. Select Upload a Local File, Browse to <js-install>/samples/resource_bundles/sales.properties, and 
select it. The path to the resource bundle appears in the Upload a Local file field. 

c. In Locate File Resource, click Next. The Add a Report Resource page indicates that the file was 
successfiilly loaded and automatically detected as a resource bundle. 

d. Enter the following information: 

• Name — sales . properties 

• Resource ID — sales .properties 

• Description — Default English resource bundle 

4. Click Next. 

5. Add and upload the Romanian Resource bundle: 

a. On the Controls & Resources page, click Add Resource. 

b. Select Upload a Local File, Browse to the file <js-install>/samples/resource_bundles/sales_ 
ro.properties, and select it. 

c. In Locate File Resource, click Next. The Add a Report Resource page shows that uploading the file 
was successful. The server recognized the type (resource bundle) and name (sales_ro.properties) of the 
selected resource. 

d. Enter the following information: 

• Name — sales_ro. properties 

• Resource ID — sales_ro.properties 

• Description — Romanian resource bundle 

e. Click Next. Controls & Resources lists all the files. 


Add JasperReport: New Complex Report 


Controls & Resources 


Data Source 


Customization 


Controls & Resources 

Locate the controls and resources used by your report. 

Resources 

Scriptlet 
sales, properties 
sales_ro. properties 
Sa lesByMonth Deta il 
Logo 

Add Resource 


JAR 

Resource Bundle 
Resource Bundle 

Added 

Added 


Input Controls 
Add Input Control... 

Input Control Options 
Display Mode: 

I Pop-up window ^ I I I Always prompt 
Optional JSP Location: 

i 

(within /WEB-INF/jsp) 


Remove 

Remove 

Remove 


Submit 


Cancel 


Figure 6-14 List of Detected and Undetected Fiie Resources 
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If you want to upload a different file for a named resource, click its resource ID in the Resources list and 
locate the new file or repositoiy object. You can change the name and description of the resource, but not its 
resource ID. If there’s a mistake in a resource ID: 

• Locate the ID in the list of resources on the Controls & Resources page, and click Remove. 

• Re-add the resource, entering the correct resource ID. 


6.4.2 Adding Input Controls 

Input controls are graphical widgets the server displays with the report. Input controls perform the following 
hmctions: 

• Prompt the user for input 

• Validate the format of the input 

• Pass the input to the report 

Based on the input, the server modifies the WHERE filter clauses in SQL parametrized queries. 

Input controls correspond to the parameters defined in JRXML reports, such as $P{name}. The server maps the 
value the user enters for the input control to the parameter of the same name. If you define an input control in 
the JasperReport and the server can’t find a parameter by the same name in the JRXML, the input control won’t 
hmction when the report mns. 


The JRXML can define a default value for the input control. To prevent users from changing the default, 
you can make the input control read-only or invisible. 


When you create an input control, you provide a datatype. Datatypes define the expected input (numbers, text, 
date, or date/time) and can include range restrictions that the server enforces. The server uses the datatype to 
classify and validate the data. 

To define a datatype, set properties on the Set the Datatype Kind and Properties page. Properties differ for other 
datatypes that appear on the page. 


Type 

The classification of the data, which can be Text, Number, Date, or Date-Time. 

Name 

The name of the datatype. 

Resource ID 

The unique ID of the datatype that you cannot edit. 

Description 

Any additional information you provide about the datatype. 

Pattern 

A regular expression that restricts the possible values of the field for the Text data type. 

Minimum vaiue 

The lowest permitted value for the field. 

Maximum vaiue 

The highest permitted value for the field. 

Minimum is Strict 

If checked, the maximum value itself is not permitted; only values less than the 
maximum value are permitted. 

Maximum is Strict 

If checked, the minimum value itself is not permitted; only values greater than the 
minimum value are permitted. 
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After determining the list of values to be presented to the user, choose one of these widget types for the input 
control: 

• Boolean - A check box widget for entering a yes/no value. 

• Single value - A text, number, date, or date/time widget. Input can be constrained to a minimum value, 
maximum value, or both. Text input can also be constrained by a matching pattern. A text box widget for 
entering a value, or a calendar for selecting date and date/time. 

• Multiple values - To present a static or a dynamic list of values to the user, choose one of these: 

• Drop-down list to select a single value 

• Radio buttons to select a single value 

• Multi-select list to select multiple values 

• Check boxes to select multiple values 

The query in the SalesByMonth.jrxml file has several input control parameters, one for each type of input 
control. These procedures show you how to add each type to the report unit. 

6.4.2.1 Adding a Text Input Control 

The simplest input control is a text box. In this example, the datatype for the input value is a number; the server 
verifies that the user enters a number into the text box. 

To add a text input control to the complex report example: 

1. After completing steps in ^‘Uploading Undetected File Resources” on page 187, click Controls & 
Resources in the JasperReport wizard. 

2. On the Controls & Resources page, click Add Input Control. The Locate Input Control page appears. 

3. Select Define an Input Control in the next step. 

4. Click Next. 

5. On the Create Input Control page, accept the default (Single Value) from the Type drop-down. 

6. Enter the other properties for the input control: 

The name is referenced in the main JRXML file, so enter it exactly as shown. 

• Prompt Text - The label the user sees next to the widget for this input: Text input Control 

• Parameter Name - The name of the report parameter that receives the user value: Text input 

• Description - An optional description that appears only within the report wizard: leave blank in this 
example. 

• Mandatoiy, Read-only, Visible - A setting that determines how the input control appears: check only 

Visible. 
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Add Input Control 

Create Input Control 

First, select the kind of input control you wish to add, then enter the required property values. 

Type: | Single Value | 

Prompt Text (required): 

I^Text Input Control 

The label t displayed to users next to the input control. 

Parameter Name (required): 
j^Textlnput 

This value must match the name of the parameter in your report. 

Description: 


O Mandatory 
Q Read-only 
C9 Visible 

Next Cancel 


Figure 6-15 Properties of the Text Input Control 


To reuse an input control, add it to the repository independent of any report using Add Resource > 
Input Control. Before using the input control in a report, check that the parameter name in the JRXML 
matches the name in the Create Input Control page. If it doesn't the server can’t run the report. 


7. Click Next. 

8. In Locate Datatypes, select Define a DataType in the next step and click Next: 



Instead of defining a datatype, you can use one in the repository if its type and range are compatible 
with your input control. 


9. In Set the Datatype Kind and Properties, enter the properties for the datatype: 

a. In Type, select Number from the drop-down as the type of data the user can enter. 



The number format allows users to enter integers and decimals. 


b. Enter a name - integer Type 

c. Enter a resource ID - lnteger_Type 

The name and resource ID are required, but are visible only when defining the input control. 
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Add Datatype 

Set the Datatype Kind and Properties 

First, select the kind of datatype you wish to add, then enter the required property values. 

Type: [Number >^ | 

Name (required): 

Integer Type 

Resource ID (required): 

Integer_Type 

Description: 


Minimum value: 


Maximum value 


D Minimum is Strict 
CD Maximum is Strict 


Save 


Cancel 


Figure 6-16 Integer Datatype Properties 

d. Leave these properties blank in this example: 

• Description - An optional description that appears only within the report wizard. 

• Minimum value - The lower bound of the value the user may enter. 

• Maximum value - The upper bound of the value the user may enter. 

• Minimum is strict - Means the minimum value itself is not allowed. 

• Maximum is strict - Means the maximum value itself is not allowed. 

10. Click Save. 

The Controls & Resources page now lists the Text Input Control. 
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Add JasperReport: New Complex Report 


Setup 

Controls & Resources 


Data Source 
Query 

Customization 


Controls & Resources 

Locate the controls and resources used by your report. 

Resources 

Scriptlet 
sales, properties 
sales_ro. properties 
5a lesByMonth Detail 
Logo 

Add Resource 


JAR 

Resource Bundle 


Resource Bundle 

Added 

Added 


Remove 

Remove 

Remove 


Input Controls 

Text Input Control Input Control Remove 

Add Input Control... 

Input Control Options 
Display Mode: 

I Pop-up window | | | Always prompt 

Optional J5P Location: 

(within /WEB-INF/jsp) 


Submit 


Cancel 


Figure 6-17 Text Input Control in Input Controls List 

6.4.2.2 Adding a Simple Check Box Input Control 

A check box input control accepts true/false (boolean) input from the user. 

To add a simple check box input control to the complex report example: 

1. Continuing with the previous example, on the Controls & Resources page, click Add Input Control. 

2. On the Locate Input Control page, click Define an input Controi in the next step. 

3. Click Next. 

4. On the Create Input Control page, select Boolean from the Type drop-down. 

5. Enter the other properties; 

• Prompt Text — Check Box Input Control 

• Parameter Name - Checkbox input. Enter the parameter name exactly as shown because the main 
JRXML file references this name. 

• Description - Leave blank in this example. 

• Mandatory, Read-only, Visible - Check only visible. 

6. Click Submit. The Controls & Resources page appears with the new check box input control. 

6.4.2.3 Adding a Drop-Down Input Control 

The drop-down input control, also called a list, gives the user a pre-determined list of choices. As a report 
designer, you make these decisions about a drop-down input control: 

• To present a single-select or multi-select list to the user 

• To present a single choice as a drop-down list or a set of radio buttons 

• To present a multi-select control as a multi-select list or a set of check boxes 

Radio buttons and check boxes usually work well for five or fewer choices. This example shows how to create 
an input control that presents three choices in a drop-down list. You can create a new list of values for this 
input control or use a list of values in the repository. 
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To add a drop-down input control to the complex report example: 

1. Continuing with the previous example, on the Controls & Resources page, click Add Input Control. 

2. On the Locate Input Control page, click Define an Input Control in the next step. 

3. Click Next. 

4. On the Create Input Control page, select Single-select List of Values from the Type drop-down. 

5. Enter the other properties: 

• Prompt Text — List Input Control 

• Parameter Name - List input Enter the parameter name exactly as shown because the main JRXML 
file references this name. 

• Description - Leave blank in this example. 

• Mandatory, Read-only, Visible - Check only visible. 

6. Click Next. 

7. On the Locate List of Values page, select Define a list of values in the next step. 



Instead of defining a list of values, you can use one in the repository if its values are compatible with 
the parameter defined in the JRXML report. 


8. Click Next. 

9. On the Add List of Values page, enter a name, resource ID, and optional description for the list of values. 
These properties aren’t visible outside of the input control. Enter these values: 

• Name — list type 

• Resource ID - list type 

• Description - Leave blank in this example. 

10. In the Name Value panel, enter names and values to present as choices to the user: 

• Enter unique names. The server requires unique names to distinguish which item the user chose. 

• Enter values of the type that match the parameter definition in the JRXML report. 

After entering a name and value, click Add. If you make a mistake click Remove. 

For this example enter: 

• Name First Item with value 1. 

• Name Second Item with value 2. 

• Name Third Item with value 3. 
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Add List of Values 

Add List of Values 

Identify the list, then create the name-value pairs. 


Name (required); 

I list type 

Resource ID (required): 

[ list type ~ 

Description: 


Name 
First Item 
Second Item 
Third Item 


Remove 

Remove 

Remove 

Add 


Submit 


Figure 6-18 Definition of the List of Values 

11. Click Submit. The Controls & Resources page appears with the new List Input control. 

6.4.2.4 Adding a Date Input Control 

This example uses a datatype from the sample data in the repository. 

To add a date input control to the complex report example: 

1. On the Controls & Resources page click Add Input Control. 

2. On the Locate Input Control page select Define an Input Control in the next step, then click Next. 

3. On the Create Input Control page, select Single-Value from the Type drop-down. 

4. Enter the other properties: 

• Prompt Text — Date Input Control 

• Parameter Name - Date input Enter the parameter name exactly as shown because the main JRXML 
file references this name. 

• Description - Leave blank in this example. 

• Mandatory, Read-only, Visible - Check only Visible. 

5. Click Next. 

6. On the Locate Datatypes page select Select a Datatype from the Repository. 

7. Click Browse. 

8. In Select Resource from Repository, expand Input Data Types, and select the Date Datatype. 

9. Click Select. The Locate DataTypes page shows the location of this datatype in the repository, 

/dat aty p es/D at eD at aty p e. 

10. Click Next. The Controls & Resources page appears with the new Date Input Control. 
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6.4.2.5 Adding a Query-Based Input Control 

A queiy-based input control presents a dynamically-created list of choices to the user. The server performs a 
queiy whose results are used to create the list of choices. You must perform the following tasks: 

• Configure the queiy. 

• Designate how to display the results in the input control. 

• Specify the value to pass as the corresponding parameter. 

To add a query-based input control to the complex report example: 

1. On the Controls & Resources page, click Add Input Control. 

2. On the Locate Input Control page, select Define an Input Control in the next step. 

3. Click Next. 

4. On the Create Input Control page, select Single-select Query from the Type drop-down. 

5. Enter the naming properties for the input control: 

• Prompt Text — Query Input Control 

• Parameter Name - Queryinput Enter the parameter name exactly as shown because the main JRXML 
file references this name. 

• Description - Leave blank in this example. 

• Mandatoiy, Read-only, Visible - Use the default settings in this example. 

6. Click Next. The Locate Query page appears. Options are: 

• To locate a reusable queiy in the repositoiy 

• To define a new queiy dedicated to this input control 

7. For this example, select Define a Query in the next step. 

8. Click Next. 

9. On the Name the Queiy page, enter naming properties for the new queiy. For this example, enter 
testQuery in both the Name and Resource ID fields. 


Add Query: 

Name the Query 

Enter the required property values. 


• Name the Query 
Link a Data Source 
Define the Query 


Name (required): 
testQuery 

Resource ID (required): 
testQuery 

Description: 


Next Cancel 


Figure 6-19 Entering a Query Name 
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10. Click Next. The Link a Data Source to the Report page appears. Options are: 

• To use the same data source for the input control as you use for the report 

• To define a new data source, dedicated to this input control 

• To select a reusable data source from the repository 

11. For this example, select Do not link a data source to use the same data source for the input control as 
you use for the report. You will select the data source for the report in ^‘Selecting a Data Source for 
Running the Complex Report” on page 200. 


Add Query: testQuery 


Link a Data Source to the Query 

Optionally, link a data source to the query- You can choose a data source from the repository or create a new one. 


Name the Query 
• Link a Data Source 
Define the Query 


@> Do not link a data source 
O Click here to create a new data source 
O Select data source from repository 


Previous Next Cancel 


Figure 6-20 Data Source Link for the Query input Controi 

12. Click Next. 

13. On the Define the Query page, select SQL from the Query Language drop-down. 

14. Enter this Query String to retrieve the labels and values to be displayed for this input control: 

SELECT user_name, first_name, last_name FROM users 


Add Query: testQuery 

Define the Query 

Select a language and enter the query 


Name the Query 
Link a Data Source 
• Define the Query 


Query Language: | SQL 
Query String: 

SELECT user_name, fir5t_name, last_name FROM users| 


Previous 


Save 


Cancel 
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Figure 6-21 Query String Definition 

15. Click Save. 

16. For each row in the results of the query, the server presents a single value, such as Sarah Smith, in the input 
type widget (drop-down, radio buttons, multi-choice, check boxes). On the Queiy Information page, name 
the database columns to comprise the input value presented to the user. The column names must exactly 
match those in the select clause of the query string: 

a. In the Value Column enter the user_name. 

b. In the Visible Column enter f irst_name. 

c. Click Add. 

d. In the Visible Column enter last_name. 

e. Click Add. 

For each column you want to display as a choice, enter the name then click Add. If you make a 
mistake click Remove. 

17. Click Submit. The Controls & Resources page displays all the resources, including the new input controls. 
Figure 6-22 on page 200 shows these resources. 

6.4.2.6 Setting the Input Control Options 

In this procedure, you set the display mode in Input Control Options at the bottom of the Controls & 
Resources page. Figure 6-22 on page 200 shows these options. 

To configure the appearance of the input controls for the complex report example: 

1. Select Pop-up window. 


You can also select Separate page to display the input controls in a separate browser window, Top of 
page to display them above the report, or In page to display them on the side of the report. 


2. Check Always prompt when you want the server to display the Input Controls dialog to prompt the user 
when the report mns. 



The definition of input controls in this example specified Visible and not Mandatory. When input controls 
aren’t mandatory and Always prompt isn’t checked on the Controls & Resources page, the user must click 
the Options button in the report viewer to change input controls; otherwise the report runs with default 
input controls 


3. Leave Optional JSP Location blank for this example. 

You can use the Optional JSP Location option to specify the path to a JSP file that affects the appearance 
of the input controls. 
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Add JasperReport: New Complex Report 


Controls & Resources 


Data Source 


Customization 


Controls & Resources 

Locate the controls and resources used by your report. 

Resources 

Scriptlet 
sales, properties 
sales_ro. properties 
Sa lesBy Month Oeta il 
Logo 

Add Resource 

Input Controls 
Text Input Control 
Check Box Input Control 
List Input Control 
Date Input Control 
Query Input Control 
Add Input Control... 

Input Control Options 
Display Mode: 

I Pop-up window ^ I ^3 Always prompt 
Optional JSP Location: 

I 

(within /WEB-INF/jsp) 


JAR 

Resource Bundle 
Resource Bundle 


Added 

Added 


Input Control 
Input Control 
Input Control 
Input Control 
Input Control 


Remove 

Remove 

Remove 


Remove 

Remove 

Remove 

Remove 

Remove 


Submit 


Cancel 


Figure 6-22 Input Controls and Resources 

Select the data source to finish the complex report example. 


.4.3 Selecting a Data Source for Running the Complex Report 

You select a data source to retrieve data for the report and the query input control; otherwise the report and the 
list of users in the query input control will be blank. 

To select a data source and run the complex report: 

1. On the Controls & Resources page of the JasperReport wizard, select Data Source. 

2. On the Locate Data Source page, choose Select data source from repository. 

3. Click Browse, choose Organization > Data Sources > JServerJNDI Data Source, and lick Select. 

4. On Link a Data Source to the Report, click Submit. 

5. On the Locate Query Page, click Submit again to save the complex report. 

Skip the Query and Customization pages of the JasperReport wizard to use the default settings on those 
pages. 

The server validates the report and a message appears indicating that the report was added to the repository. 

6. In the Repository, click the name New Complex Report to mn and view the report. 

Input controls appear. 

7. Enter these input values, as shown in Figure 6-23: 

a. Text Input Control: myText 

b. Check Box Input Control: Check the checkbox. 
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c. List Input Control: Select Third Item. 

d. Date Input Control: Click ^ and select December 31, 2010. 

e. Query Input Control: Select Sarah Smith from the drop-down. 


Input Controls 


Text Input Control 

myText 

Check Box Input Control 
List Input Control 

Third Item 

Date Input Control 

I 2012-06-27 I M 

Query Input Controls 


[Null] I Administrator 
Jim I Brennan 
Emil I Marinescu 
Vital I Rahman _ 


" Sarah | Smith 


Sally I Bronsen 
Max I Jensen 
Will I Westin 
Chris I Olliver 
Beth I Sasseen 
Kristen | Verona 
Jaime | Mesquite 
Matt I Dominic 


Figure 6-23 Input Controls Dialog for the New Complex Report 

8. Click OK or Apply to mn the report with the selected input, including the incorrect non-numerical input 
for the Text Input Control. 

The server enforces the proper format defined for each input control. You defined the Text Input Control as 
a numeric type, so it accepts only valid numbers, as indicated by the message to specify a valid float 
number, as shown in Figure 6-24. 
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Input Controls 


Text Input Control 


1 myText 

1 

Specify a valid value for type BigDecimal. 

[^Check Bdk Input Control 

List Input Control 


Third Item 


Date Input Control 

2012-06-27 

1 inni 

Query Input Controls 



Sarah | Smith 


Apply 


□ K Reset Cancel 


Figure 6-24 Invalid Input Message 

9. In Text Input Control, enter 3 and click OK or Apply. 

The sample report includes a header that displays the value of each parameter received from the input 
controls. Values and labels appear in the language specified by the active resource bundle, in this case 
English. 


Nevj CompleK Report Data refreshed Jun 27, 2012 at 9:09:31 PM 

Page 1 of 151 ► ^ Back ^ ^ ^ 


QJASPER Sales By Month Report 
Checkbox checked 
List item 3 

Date Jun 27, 2012 

Query item sarah 

User jasperadmin 

User 



Sarah Smith N & W Creek Transportation Corp 600.00 

_ 0 & D Rutledge Communications Associat _ 1900.00 

Wolter-Collins Construction Partners 1630.00 

Sally Bronsen Rutledge-Cavestany Transportation 1100.00 

_ Company _ 

M & Y Planck Communications. Ltd 1330.00 


Figure 6-25 Output Controlled by Input 

In the report viewer, you can open the Input Controls dialog at any time by clicking the Options button. 
Click OK to mn the report using the chosen values and close the Input Controls dialog; click Apply to mn 
the report using the chosen values, but keep the Input Controls open for choosing other values and re- 
mnning the report. 
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If you get an error when you run the report, open it for editing as described in “Editing JRXML Report 
Units” on page 203. Review your settings. If you can’t find the problem, edit the SalesByMonth sample 
report (in the repository at/reports/samples) and compare its settings to your report. 


To see the message written by the scriptlet JAR on the last page of the report, click in the report 

viewer. 


5 Adding Cascading Input Controls to a Report 

JRXML-based reports can include input controls that have dynamic values. The values depend on a user’s 
selection in other input controls. For example, a report has input controls for country, state, and city. The 
options in the State input control depend on the value selected in the Country input control. When the user 
selects a state, the list of City values includes only those in the selected state. These cascading input controls 
use queries to determine the values to display in each input control field. 

To use input controls as parameters for a queiy that populates another input control, you use a special syntax to 
reference a parameter name in the input control’s queiy. The syntax is identical to the $P{parameter_name} 
and $X{ . . . } syntax used in queries for . 

For example, a report returns data identified by country and city. It includes input controls called COUNTRY 
and CITY. COUNTRY is a query-based input control that returns the list of countries in the data source. CITY 
is also a query-based input control, but its query uses COUNTRY as input: 


select address_city from accounts where $X{EQUALS, address_country, COUNTRY} 


When the user selects a country from the COUNTRY input control, the value selected is used by the query of 
the CITY input control. The CITY input control is refreshed to show the list of cities for the chosen country. 
Making two selections from smaller lists is much clearer and quicker for report users. For an example of viewing 
a report that has cascading input controls, see ^‘Cascading Input Controls” on page 74. 

Note that there are other ways to use a parameter in a query. For details about the $P and $X syntax and an 
example of creating a cascading input control, see the TIBCO JasperReports Server Administrator Guide. 


6 Editing JRXML Report Units 

After you add a report unit to the repository, you can edit any of its elements, including file resources and input 
controls. This example modifies the display text of the ambiguous Text Input Control. 

To edit the complex report example: 

1. Log into the server as an administrator and select View > Repository 


If you log in as a user, you can edit a report that you created. This example requires an administrator login 
because an administrator created the complex report. 

2. Search or browse the repository to locate the report. In this example, go to Organization > Reports. 

3. Right-click the New Complex Report and select Edit from the context menu. The JasperReport wizard 
opens the report unit. 

4. Navigate to the page of the wizard for making the change; in this example, click Controls & Resources. 
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5. Make changes to an input control prompt and the display mode of the input controls, for example: 

a. Click the name of the Textinput control. The Locate Input Control page shows that this input control 
is locally defined. 

b. Click Next. The Create Input Control page appears. 

c. Change the contents of the Prompt Text field to Enter a number. Click Next. The Locate Datatypes 
page appears. You can select a different datatype from the repository. For this example, accept the 
existing datatype setting. 

d. In Locate Datatypes, click Next. 

e. In Set the Datatype Kind and Properties, click Save to accept the datatype property settings. 

6. On the Controls & Resources page: 

a. Change the Display Mode to In Page. 

b. Clear the Always prompt check box. 

c. Click Submit. 

7. Run the New Complex Report again. 

Instead of appearing in a pop-up before the report, the input controls appear in the Filters panel of the 
report. In Figure 6-26 you can see the new prompt Enter a number for the text input control. Because 
none of the input controls in this example are required, the report can display with blank input controls. 
Enter values and click Apply to modify the report output according to your input. 


LI Options 
Enter a number. 


New Complex Report Data refreshed Jun 21. 2012 at 9!l5!29 PM 
ii 4 Page [l ^ of 151 ► ^ 


O 

Back 


0. K.. 


O Check Box Input Control 
List Input Control 


Date Input Control 

' m 

Query Input Controls 


B JASPER Sales By Month Report 

RbPORIS J • 

Checkbox checked 
List item 1 

User jasperadmin 

User 


Apply 


Reset 


1 November, 2002 

12880.00 1 

1 Sales person 

Account 

Amount 1 

Sarah Smith 

N & W Creek Transportation Corp 

600.00 


0 & D Rutledge Communications Associat 

1900.00 


Wolter-Collins Construction Partners 

1630.00 

Sally Bransen 

Rutledge-Cavestany Transportation 

Company 

1100.00 


M & Y Planck Communications. Ltd 

1330.00 

Maxjensen 

B & D Wolter Machinery Partners 

1930.00 




Figure 6-26 Output of the Modified Report 


.7 Localizing Reports 

You can adapt reports to global audiences by localizing input controls and field names: 

• Input controls - The server supports multi-lingual prompts and static lists of values in reports. 

• Field names - The server supports multi-lingual field names in reports. 

A $R expression that you write in the report design triggers linguistic changes in the report output for different 
locales. Each $R expression refers to a name-value pair (your translations) in a resource bundle. A resource 
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bundle file is a text file that has a .properties extension. You create a resource bundle in Jaspersoft Studio or 
a text editor. You set the base name of the resource bundle in the header of the JRXML file: 


<jasperReport name="StoreSales" pageWidth="595" pageHeight="842" columnWidth="515" 
leftMargin="40" rightMargin="40" topMargin="50" bottomMargin="50" 
resourceBundle="simpleTable"> 


For example, simple Table is the base name of the resource bundle file for this report. If you prefer using a 
graphical user interface to coding in XML, use Jaspersoft Studio to set the base name of the resource bundle. 


.7.1 Running a Localized Report 

In this procedure, you mn the Romanian version of the complex report that you added in ‘‘Uploading 
Undetected File Resources” on page 187. 

To run the Romanian version of the complex report: 

1. Choose the Romanian locale on the login page of the server, and login as an administrator. 

2. Click View > Repository, and navigate to Organization > Reports. 

3. Click the name of the complex report. New Complex Report. The Input Controls dialog appears. 

4. Enter input control values: 

a. Text Input Control: 3 

b. Check Box Input Control: Check the check box. 

c. List Input Control: Select Third Item. 

d. Date Input Control: Click ^ and select March 31, 2010. 

e. Queiy Input Control: Select Sarah Smith from the drop-down, 
f Click OK. 

The fields in the title band and column names (sales person, sales account, and sales amount), shown in 
Figure 6-27, appear in the language set by the Romanian resource bundle sales_ro.properties: 


title=Raport al v\u00E2nz\u0103rilor lunare 
sales.person=Agent de v\u00E2nz\u0103ri 
sales.account=Client 
sales.amount=Sum\u0103 
param.number=Num\u0103r 
param.date=Dat\u0103 


The currency and dates in the report output header map to Romanian locale settings. 
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.7.2 


Page 1 


of 151 ► ^ 


Back 




BSJASPER 


Raport al vanzarilor lunare 
Numar 3 

Checkbox checked 
List item 3 

Data 31.03.2010 

Query item sarah 

User jasperadmin 

user 



Sarah Smith N &W CreekTransportation Corp 600,00 

0 & D Rutledge Communications Associates 1900,00 


Figure 6-27 A Report Localized for the Romanian Locale 

By default, the web interface elements appear in US English when you choose an unsupported locale, such as 
the Romanian locale. If you choose a supported language, the web interface elements appear in that language. 
Supported languages are Chinese (Simplified), French, German, Japanese, and Spanish. You can customize the 
server to support additional languages. You can translate the web interface into a different language, server 
property names, and messages in another language. For some locales, you may also need to change the default 
locale and time zone. For more information about localizing the server, see the TIBCO JasperReports Server 
Administrator Guide. 


Reusing Domain Localization Files 

The location of a resource bundle determines whether ifs reusable and the conditions under which the server 
uses it. To resolve a $R expression in a report, the server scans resource bundles at two levels in the order 
described in this table. 


Order 

Level 

Description 

1 

Report/ 

Repository 

A report-level bundle declares the resource bundle base name in the header of its 

JRXML file. The Romanian resource bundle is a report-level bundle. A repository-level 
bundle is independent of any specific report and can be linked to multiple reports, as 
described in TIBCO JasperReports Server Data Management Using Domains. 

2 

Server 

A server-wide bundle typically contains server messages and labels of user interface 
components, as described in the TIBCO JasperReports Server Administrator Guide. This 
bundle typically resides in the WEB-INF/bundles directory of the server. 


First, the server searches the report/repository level and stops scanning resource bundles if it finds a resolution to 
the $R expression. If the server does not find a resolution, it scans the server level for the resource ID of the 
field and uses this ID. 
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Chapter 6 Adding Reports Directly to the Repository 


6.7.3 Using Default Fonts in JasperReports Server 

By default, the server uses three fonts for reports: 

• DejaVu Sans 

• DejaVu Serif 

• DejaVu Sans Mono 

Using the DejaVu fonts shipped with the server ensures availability of fonts in all environments; the PDF is 
pixel-perfect eveiy time. 

The DejaVu fonts replace the Java logical fonts used in previous versions of the server: 

• SansSerif 

• Serif 

• Monospaced 


SansSerif, Serif, Monospaced can still be used, but are deprecated because these Java logical fonts map 
to different TTF files in different environments, and run the risk of text being cut when exported to PDF due 
to font metric mismatches. Also, these Java logical fonts aren't recognized by some browsers, resulting in 
font substitutions. For example, Firefox in a Windows environment renders the SansSerif logical font as 
Serif. 


When using the DejaVu fonts coming from font extensions, you don’t need to set any other font attributes (such 
as the pdfXXX attributes) in the JRXML or specify font mapping. The font extension file that makes these fonts 
available sets font attributes and mapping. 

For more information about DejaVu, refer to its SourceForge project at: 
http ://dej avu-fonts.org/wiki/index .php?title=Main_Page. 



When you upload a TrueType font to the repository, the file name must include the correct extension 
(.TTF). 
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Ad Hoc Editor 

The interactive data explorer in JasperReports Server Professional and Enterprise editions. Starting from a 
predefined collection of fields, the Ad Hoc Editor lets you drag and drop fields, dimensions, and measures to 
explore data and create tables, charts, and crosstabs. These Ad Hoc views can be saved as reports. 

Ad Hoc Report 

In previous versions of JasperReports Server, a report created through the Ad Hoc Editor. Such reports could be 
added to dashboards and be scheduled, but when edited in Jaspersoft Studio, lost their grouping and sorting. In 
the current version, the Ad Hoc Editor is used to explore views which in turn can be saved as reports. Such 
reports can be edited in Jaspersoft Studio without loss, and can be scheduled and added to dashboards. 

Ad Hoc View 

A view of data that is based on a Domain, Topic, or OLAP client connection. An Ad Hoc view can be a table, 
chart, or crosstab and is the entiy point to analysis operations such as slice and dice, drill down, and drill 
through. Compare OLAP View. You can save an Ad Hoc view as a report in order to edit it in the interactive 
viewer, schedule it, or add it to a dashboard. 

Aggregate Function 

An aggregate function is one that is computed using a group of values; for example. Sum or Average. Aggregate 
ftmctions can be used to create calculated fields in Ad Hoc views. Calculated fields containing aggregate 
ftmctions cannot be used as fields or added to groups in an Ad Hoc view and should not be used as filters. 
Aggregate functions allow you to set a level, which specifies the scope of the calculation; level values include 
Current (not available for PercentOf), ColumnGroup, ColumnTotal, RowGroup, RowTotal, Total. 

Amazon Web Services (AWS) 

Cloud platform, used to provide and host a family of services, such as RDS, S3, and EC2. 

Analysis View 

See OLAP View. 

Audit Archiving 

To prevent audit logs from growing too large to be easily accessed, the installer configures JasperReports Server 
to move current audit logs to an archive after a certain number of days, and to delete logs in the archive after a 
certain age. The archive is another table in the JasperReports Server's repository database. 
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Audit Domains 

A Domain that accesses audit data in the repository and lets administrators create Ad Hoc reports of server 
activity. There is one Domain for current audit logs and one for archived logs. 

Audit Logging 

When auditing is enabled, audit logging is the active recording of who used JasperReports Server to do what 
when. The system installer can configure what activities to log, the amount of detail gathered, and when to 
archive the data. Audit logs are stored in the same private database that JasperReports Server uses to store the 
repository, but the data is only accessible through the audit Domains. 

Auditing 

A feature of JasperReports Server Enterprise edition that records all server activity and allows administrators to 
view the data. 

Calculated Field 

In an Ad Hoc view or a Domain, a field whose value is calculated from a user-defined formula that may include 
any number of fields, operators, and constants. For Domains, a calculated field becomes one of the items to 
which the Domain's security file and locale bundles can apply. There are more functions available for Ad Hoc 
view calculations than for Domains. 

CloudFormation (CF) 

Amazon Web Services CloudFormation gives developers and systems administrators an easy way to create and 
manage a collection of related AWS resources, provisioning, and updating them in an orderly and predictable 
fashion. 

CRM 

Customer Relationship Management. The practice of managing eveiy facet of a company's interactions with its 
clientele. CRM applications help businesses track and support their customers. 

CrossJoin 

An MDX function that combines two or more dimensions into a single axis (column or row). 

Cube 

The basis of most OFAP applications, a cube is a data stmcture that contains three or more dimensions that 
categorize the cube's quantitative data. When you navigate the data displayed in an OFAP view, you are 
exploring a cube. 

Custom Field 

In the Ad Hoc Editor, a field that is created through menu items as a simple fimction of one or two available 
fields, including other custom fields. When a custom field becomes too complex or needs to be used in many 
reports, it is best to define it as a calculated field in a Domain. 

Dashboard 

A collection of reports, input controls, graphics, labels, and web content displayed in a single, integrated view. 
Dashboards often present a high level view of your data, but input controls can parametrize the data to display. 
For example, you can narrow down the data to a specific date range. Embedded web content, such as other web- 
based applications or maps, make dashboards more interactive and functional. 

Dashlet 

An element in a dashboard. Dashlets are defined by editable properties that vaiy depending on the dashlet type. 
Types of dashlet include reports, text elements, filters, and external web content. 
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Data Island 

A single join tree or a table without joins in a Domain. A Domain may contain several data islands, but when 
creating an Ad Hoc view from a Domain, you can only select one of them to be available in the view. 

Data Policy 

In JasperReports Server, a setting that determines how the server processes and caches data used by Ad Hoc 
reports. Select your data policies by clicking Manage > Server > Settings Ad Hoc Settings. By default, this 
setting is only available to the supemser account. 

Data Source 

Defines the connection properties that JasperReports Server needs to access data. The server transmits queries to 
data sources and obtains datasets in return for use in filling reports and previewing Ad Hoc reports. 
JasperReports Server supports JDBC, JNDI, and Bean data sources; custom data sources can be defined as well. 

Dataset 

A collection of data arranged in columns and rows. Datasets are equivalent to relational results sets and the 
jRDataSource type in the JasperReports Libraiy. 

Datatype 

In JasperReports Server, a datatype is used to characterize a value entered through an input control. A datatype 
must be of type text, number, date, or date-time. It can include constraints on the value of the input, for example 
maximum and minimum values. As such, a datatype in JasperReports Server is more stmctured than a datatype 
in most programming languages. 

Denormalize 

A process for creating table joins that speeds up data retrieval at the cost of having duplicate row values 
between some columns. 

Derived Table 

In a Domain, a derived table is defined by an additional query whose result becomes another set of items 
available in the Domain. For example, with a JDBC data source, you can write an SQL query that includes 
complex functions for selecting data. You can use the items in a derived table for other operations on the 
Domain, such as joining tables, defining a calculated field, or filtering. The items in a derived table can also be 
referenced in the Domain's security file and locale bundles. 

Dice 

An OLAP operation to select columns. 

Dimension 

A categorization of the data in a cube. For example, a cube that stores data about sales figures might include 
dimensions such as time, product, region, and customer's industry. 

Domain 

A virtual view of a data source that presents the data in business terms, allows for localization, and provides 
data-level security. A Domain is not a view of the database in relational terms, but it implements the same 
frmctionality within JasperReports Server. The design of a Domain specifies tables in the database, join clauses, 
calculated fields, display names, and default properties, all of which define items and sets of items for creating 
Ad Hoc reports. 
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Domain Topic 

A Topic that is created from a Domain by the Data Chooser. A Domain Topic is based on the data source and 
items in a Domain, but it allows further filtering, user input, and selection of items. Unlike a JRXML-based 
Topic, a Domain Topic can be edited in JasperReports Server by users with the appropriate permissions. 

Drill 

To click on an element of an OLAP view to change the data that is displayed: 

• Drill down. An OLAP operation that exposes more detailed information down the hierarchy levels by 
delving deeper into the hierarchy and updating the contents of the navigation table. 

• Drill through. An OLAP operation that displays detailed transactional data for a given aggregate measure. 
Click a fact to open a new table beneath the main navigation table; the new table displays the low-level 
data that constitutes the data that was clicked. 

• Drill up. An OLAP operation for returning the parent hierarchy level to view to summaiy information. 

Eclipse 

An open source Integrated Development Environment (IDE) for Java and other programming languages, such as 
C/C++. 

ETL 

Extract, Transform, Load. A process that retrieves data from transactional systems, and filters and aggregates the 
data to create a multidimensional database. Generally, ETL prepares the database that your reports will access. 
The Jaspersoft ETL product lets you define and schedule ETL processes. 

Fact 

The specific value or aggregate value of a measure for a particular member of a dimension. Facts are typically 
numeric. 

Field 

A field is equivalent to a column in the relational database model. Fields originate in the stmcture of the data 
source, but you may define calculated fields in a Domain or custom fields in the Ad Hoc Editor. Any type of 
field, along with its display name and default formatting properties, is called an item and may be used in the Ad 
Hoc Editor. 

Frame 

In Jaspersoft Studio, a frame is a rectangular element that can contain other elements and optionally draw a 
border around them. Elements inside a frame are positioned relative to the frame, not to the band, and when you 
move a frame, all the elements contained in the frame move together. A frame automatically stretches to fit its 
contents. 

Group 

In a report, a group is a set of data rows that have an identical value in a designated field. 

• In a table, the value appears in a header and footer around the rows of the group, while the other fields 
appear as columns. 

• In a chart, the field chosen to define the group becomes the independent variable on the X axis, while the 
other fields of each group are used to compute the dependent value on the Y axis. 

Hierarchy Level 

In an OLAP cube, a member of a dimension containing a group of members. 
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Input Control 

A button, check box, drop-down list, text field, or calendar icon that allows users to enter a value when running 
a report or viewing a dashboard that accepts input parameters. For JRXML reports, input controls and their 
associated datatypes must be defined as repositoiy objects and explicitly associated with the report. For 
Domain-based reports that prompt for filter values, the input controls are defined internally. When either type of 
report is used in a dashboard, its input controls are available to be added as special content. 

Item 

When designing a Domain or creating a Topic based on a Domain, an item is the representation of a database 
field or a calculated field along with its display name and formatting properties defined in the Domain. Items 
can be grouped in sets and are available for use in the creation of Ad Hoc reports. 

JasperReport 

A combination of a report template and data that produces a complex document for viewing, printing, or 
archiving information. In the server, a JasperReport references other resources in the repository: 

• The report template (in the form of a JRXML file) 

• Information about the data source that supplies data for the report 

• Any additional resources, such as images, fonts, and resource bundles referenced by the report template. 

The collection of all the resources that are referenced in a JasperReport is sometimes called a report unit. End 
users usually see and interact with a JasperReport as a single resource in the repository, but report creators must 
define all of the components in the report unit. 

JasperReports lO 

An HTTP-based reporting service for JasperReports Library that provides a REST API for mnning, exporting, 
and interacting with reports and a JavaScript API for embedding reports and their input controls into your web 
pages and web applications. 

JasperReports Library 

An embeddable, open source, Java API for generating a report, filling it with current data, drawing charts and 
tables, and exporting to any standard format (HTML, PDF, Excel, CSV, and others). JasperReports processes 
reports defined in JRXML, an open XML format that allows the report to contain expressions and logic to 
control report output based on mn-time data. 

JasperReports Server 

A commercial open source, server-based application that calls the JasperReports Library to generate and share 
reports securely. JasperReports Server authenticates users and lets them upload, mn, view, schedule, and send 
reports from a web browser. Commercial versions provide metadata layers, interactive report and dashboard 
creation, and enterprise features such as organizations and auditing. 

Jaspersoft Studio 

A commercial open source tool for graphically designing reports that leverage all features of the JasperReports 
Library. Jaspersoft Studio lets you drag and drop fields, charts, and sub-reports onto a canvas, and also define 
parameters or expressions for each object to create pixel-perfect reports. You can generate the JRXML of the 
report directly in Jaspersoft Studio, or upload it to JasperReports Server. Jaspersoft Studio is implemented in 
Eclipse. 

Jaspersoft ETL 

A graphical tool for designing and implementing your data extraction, transforming, and loading (ETL) tasks. It 
provides hundreds of data source connectors to extract data from many relational and non-relational systems. 
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Then, it schedules and performs data aggregation and integration into data marts or data warehouses that you 
use for reporting. 

Jaspersoft OLAP 

A relational OLAP server integrated into JasperReports Server that performs data analysis with MDX queries. 
The product includes queiy builders and visualization clients that help users explore and make sense of 
multidimensional data. Jaspersoft OLAP also supports XML/A connections to remote servers. 

Jaspersoft Studio 

An open source tool for graphically designing reports that leverage all features of the JasperReports Library. 
Jaspersoft Studio lets you drag and drop fields, charts, and sub-reports onto a canvas, and also define parameters 
or expressions for each object to create pixel-perfect reports. You can generate the JRXML of the report directly 
in Jaspersoft Studio, or upload it to JasperReports Server. Jaspersoft Studio is implemented in Eclipse. 

JavaBean 

A reusable Java component that can be dropped into an application container to provide standard functionality. 

JDBC 

Java Database Connectivity. A standard interface that Java applications use to access databases. 

JNDI 

Java Naming and Directoiy Interface. A standard interface that Java applications use to access naming and 
directory services. 

Join Tree 

In Domains, a collection of joined tables from the actual data source. A join is the relational operation that 
associates the rows of one table with the rows of another table based on a common value in given field of each 
table. Only the fields in a same join tree or calculated from the fields in a same join tree may appear together in 
a report. 

JPivot 

An open source graphical user interface for OLAP operations. For more information, visit 
http://jpivot.sourceforge.net/ . 

JRXML 

An XML file format for saving and sharing reports created for the JasperReports Library and the applications 
that use it, such as Jaspersoft Studio and JasperReports Server. JRXML is an open format that uses the XML 
standard to define precisely all the stmcture and configuration of a report. 

Level 

Specifies the scope of an aggregate ftinction in an Ad Hoc view. Level values include Current (not available for 
PercentOf), ColumnGroup, ColumnTotal, RowGroup, RowTotal, Total. 

MDX 

Multidimensional Expression Language. A language for querying multidimensional objects, such as OLAP (On 
Line Analytical Processing) cubes, and returning cube data for analytical processing. An MDX query is the 
query that determines the data displayed in an OLAP view. 

Measure 

Depending on the context: 

• In a report, a formula that calculates the values displayed in a table's columns, a crosstab's data values, or a 
chart's dependent variable (such as the slices in a pie). 
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• In an OLAP view, a formula that calculates the facts that constitute the quantitative data in a cube. 

Mondrian 

A Java-based, open source multidimensional database application. 

Mondrian Connection 

An OLAP client connection that consists of an OLAP schema and a data source. OLAP client connections 
populate OLAP views. 

Mondrian Schema Editor 

An open source Eclipse plug-in for creating Mondrian OLAP schemas. 

Mondrian XML/A Source 

A server-side XML/A source definition of a remote client-side XML/A connection used to populate an OLAP 
view using the XML/A standard. 

MySQL 

An open source relational database management system. For information, visit http://www.mysql.com/ . 

Navigation Table 

The main table in an OLAP view that displays measures and dimensions as columns and rows. 

ODBO Connect 

Jaspersoft ODBO Connect enables Microsoft Excel 2003 and 2007 Pivot Tables to work with Jaspersoft OLAP 
and other OLAP servers that support the XML/A protocol. After setting up the Jaspersoft ODBO data source, 
business analysts can use Excel Pivot Tables as a front-end for OLAP analysis. 

OLAP 

On Line Analytical Processing. Provides multidimensional views of data that help users analyze current and past 
performance and model future scenarios. 

OLAP Client Connection 

A definition for retrieving data to populate an OLAP view. An OLAP client connection is either a direct Java 
connection (Mondrian connection) or an XML-based API connection (XML/A connection). 

OLAP Schema 

A metadata definition of a multidimensional database. In Jaspersoft OLAP, schemas are stored in the repositoiy 
as XML file resources. 

OLAP View 

Also called an analysis view. A view of multidimensional data that is based on an OLAP client connection and 
an MDX query. Unlike Ad Hoc views, you can directly edit an OLAP view's MDX query to change the data 
and the way they are displayed. An OLAP view is the entry point for advanced analysis users who want to 
write their own queries. Compare Ad Hoc View. 

Organization 

A set of users that share folders and resources in the repository. An organization has its own user accounts, roles, 
and root folder in the repositoiy to securely isolate it from other organizations that may be hosted on the same 
instance of JasperReports Server. 
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Organization Admin 

Also called the organization administrator. A user in an organization with the privileges to manage the 
organization's user accounts and roles, repository permissions, and repository content. An organization admin 
can also create suborganizations and mange all of their accounts, roles, and repository objects. The default 
organization admin in each organization is the jasperadmin account. 

Outlier 

A fact that seems incongmous when compared to other member's facts. For example, a very low sales figure or a 
very high number of help desk tickets. Such outliers may indicate a problem (or an important achievement) in 
your business. The analysis features of Jaspersoft OLAP excel at revealing outliers. 

Parameter 

Named values that are passed to the engine at report-filling time to control the data returned or the appearance 
and formatting of the report. A report parameter is defined by its name and type. In JasperReports Server, 
parameters can be mapped to input controls that users can interact with. 

Pivot 

To rotate a crosstab such that its row groups become column groups and its column groups become rows. In the 

Ad Hoc Editor, pivot a crosstab by clicking . 

Pivot Table 

A table with two physical dimensions (for example, X and Y axis) for organizing information containing more 
than two logical dimensions (for example, PRODUCT, CUSTOMER, TIME, and LOCATION), such that each 
physical dimension is capable of representing one or more logical dimensions, where the values described by 
the dimensions are aggregated using a function such as SUM. Pivot tables are used in Jaspersoft OLAP. 

Properties 

Settings associated with an object. The settings determine certain features of the object, such as its color and 
label. Properties are normally editable. In Java, properties can be set in files listing objects and their settings. 

Report 

In casual usage, report may refer to: 

• A JasperReport. See JasperReport. 

• The main JRXML in a JasperReport. 

• The file generated when a JasperReport is scheduled. Such files are also called content resources or output 
files. 

• The file generated when a JasperReport is mn and then exported. 

• In previous JasperReports Server versions, a report created in the Ad Hoc Editor. See Ad Hoc Report. 

Report Run 

An execution of a report. Ad Hoc view, or dashboard, or a view or dashboard designer session, it measures and 
limits usage of Freemium instances of JasperReports Server. The executions apply to resources no matter how 
they are mn (either in the web interface or through the various APIs, such as REST web services). Users of our 
Community Project and our full-use commercial licenses are not affected by the limit. For more information, 
please contact sales@j aspersoft.com . 

Repository 

Depending on the context: 


216 


TIBCO Software Inc. 





Glossary 


• In JasperReports Server, the repository is the tree structure of folders that contain all saved reports, 
dashboards, OLAP views, and resources. Users access the repository through the JasperReports Server web 
interface or through Jaspersoft Studio. Applications can access the repository through the web service API. 
Administrators use the import and export utilities to back up the repository contents. 

• In JasperReports 10, the repository is where all the resources needed to create and mn reports are stored. The 
repository can be stored in a directory on the host computer or in an S3 bucket hosted by Amazon Web 
Services. Users access the repository through a file browser on the host machine or through the AWS 
console. 

Resource 

In JasperReports Server, anything residing in the repository, such as an image, file, font, data source. Topic, 
Domain, report element, saved report, report output, dashboard, or OLAP view. Resources also include the 
folders in the repository. Administrators set user and role-based access permissions on repository resources to 
establish a security policy. 

Role 

A security feature of JasperReports Server. Administrators create named roles, assign them to user accounts, and 
then set access permissions to repository objects based on those roles. Certain roles also determine what 
fimctionality and menu options are displayed to users in the JasperReports Server interface. 

S3 Bucket 

Cloud storage system for Amazon Web Services. JasperReports 10 can use an S3 bucket to store files for its 
repository. 

Schema 

A logical model that determines how data is stored. For example, the schema in a relational database is a 
description of the relationships between tables, views, and indexes. In Jaspersoft OLAP, an OLAP schema is the 
logical model of the data that appears in an OLAP view; they are uploaded to the repository as resources. For 
Domains, schemas are represented in XML design files. 

Schema Workbench 

A graphical tool for easily designing OLAP schemas, data security schemas, and MDX queries. The resulting 
cube and query definitions can then be used in Jaspersoft OLAP to perform simple but powerful analysis of 
large quantities of multi-dimensional data stored in standard RDBMS systems. 

Set 

In Domains and Domain Topics, a named collection of items grouped together for ease of use in 
Editor. A set can be based on the fields in a table or entirely defined by the Domain creator, but 
set must originate in the same join tree. The order of items in a set is preserved. 

Slice 

An OLAP operation for filtering data rows. 

SQL 

Stmctured Query Language. A standard language used to access and manipulate data and schemas in a 
relational database. 

Stack 

A collection of Amazon Web Services resources you create and delete as a single unit. 


the Ad Hoc 
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System Admin 

Also called the system administrator. A user who has unlimited access to manage all organizations, users, roles, 
repository permissions, and repository objects across the entire JasperReports Server instance. The system admin 
can create root-level organizations and manage all server settings. The default system admin is the superuser 
account. 

Topic 

A JRXML file created externally and uploaded to JasperReports Server as a basis for Ad Hoc reports. Topics are 
created by business analysts to specify a data source and a list of fields with which business users can create 
reports in the Ad Hoc Editor. Topics are stored in the Ad Hoc Components folder of the repository and 
displayed when a user launches the Ad Hoc Editor. 

Transactional Data 

Data that describe measurable aspects of an event, such as a retail transaction, relevant to your business. 
Transactional data are often stored in relational databases, with one row for each event and a table column or 
field for each measure. 

User 

Depending on the context: 

• A person who interacts with JasperReports Server through the web interface. There are generally three 
categories of users: administrators who install and configure JasperReports Server, database experts or 
business analysts who create data sources and Domains, and business users who create and view reports and 
dashboards. 

• A user account that has an ID and password to enforce authentication. Both people and API calls accessing 
the server must provide the ID and password of a valid user account. Roles are assigned to user accounts to 
determine access to objects in the repository. 

View 

Several meanings pertain to JasperReports Server: 

• An Ad Hoc view. See Ad Hoc View. 

• An OLAP view. See OLAP View. 

• A database view. See http://en.wikipedia.org/wiki/View %28database%29 . 

Virtual Data Source 

A virtual data source allows you to combine data residing in multiple JDBC and/or JNDI data sources into a 
single data source that can query the combined data. Once you have created a virtual data source, you create 
Domains that join tables across the data sources to define the relationships between the data sources. 

WCF 

Web Component Framework. A low-level GUI component of JPivot. For more information, see 
http: //j pi VO t. sourceforge.net/wcEindex .html . 

Web Services 

A SOAP (Simple Object Access Protocol) API that enables applications to access certain features of 
JasperReports Server. The features include repository, scheduling and user administration tasks. 

XML 

extensible Markup language. A standard for defining, transferring, and interpreting data for use across any 
number of XML-enabled applications. 
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XML/A 

XML for Analysis. An XML standard that uses Simple Object Access protocol (SOAP) to access remote data 
sources. For more information, see http://www.xmla.org/ . 

XML/A Connection 

A type of OLAP client connection that consists of Simple Object Access Protocol (SOAP) definitions used to 
access data on a remote server. OLAP client connections populate OLAP views. 
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Dashboards 22 
moving 19 

formats for report output 69 
formatting 

columns 57, 60 
conditional 62 
FTP 80-81 
Fusion 70 


Fusion charts 70 

G 

Getting Started page 
for administrators 12 
for end users 11 
icons 11 
return button 12 

groups 

expanding and collapsing 130 
pivoting and switching 99 

H 

help 12 

I 

IDs 

organization 10 
sample user IDs 9 

input controls 
adding 190 

Always prompt option 199 
and dashboards 25, 41 
and parametrized queries 157 
as a pop-up window 43 
cascading 74, 203 
check box type 194 
compared to filters 157 
date type 196 
default values 71, 190 
design tips 52 
drop-down type 195 
in the Ad Hoc Editor 99,157 
in the Report Viewer 57 
list type 195 
localizing 51 

Optional JSP Eocation option 199 

query type 197 

reports with 71-72 

running a report with 71 

text 191 

types 190 

using 161 

Visible property 199 


TIBCO Software Inc. 


223 




TIBCO JasperReports Server User Guide 


J 

JAR files 186-187 
JasperReport wizard 

Controls & Resources 178, 186-187, 200, 203 
Data Source 170, 181, 200 
edit report unit 203 
Query 181, 183 
Setup 169,177,186 
Jaspersoft OLAP prerequisites 7 
JAWS 13 
Jobs List page 87 
jobs. See scheduling reports. 78 
JRXML files 

and D omain Topics 171 
and Topics 169-170 
external resources 187 
field names in 170, 204 
suggested file resources 179 
to create a new report 177, 186 
uploading 177 

K 

keyboard shortcuts 13 
arrow keys 13 
enter 13 
escape 13 

L 

Layout Band 100 
layouts of views 95 
Library menu 12 
Library page 

Created Date column 14 
Modified Date column 14 
locales 

expressions 204 
in Ad Hoc views 170 
showing 10 
Locate Query page 183 
logging in 

multiple organizations 10 
passwords 9 

with the default administrator login 9 


M 

mapping parameters in dashboards 45 
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See also Domain Topics. 171 
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